This is so frustrating. I am trying to find out information about the TDSRESTWebDispatcher component in XE7, so I try the help.
This is so frustrating. I am trying to find out information about the TDSRESTWebDispatcher component in XE7, so I try the help.
It has help information for TComponent, the class from which it inherits, instead. Lack of complete, quality documentation is the most frustrating part of using Delphi.
http://docwiki.embarcadero.com/Libraries/XE7/en/Datasnap.DSHTTPWebBroker.TDSRESTWebDispatcher
It has help information for TComponent, the class from which it inherits, instead. Lack of complete, quality documentation is the most frustrating part of using Delphi.
http://docwiki.embarcadero.com/Libraries/XE7/en/Datasnap.DSHTTPWebBroker.TDSRESTWebDispatcher
Gotta love it. I will say to my dying breath -- no one is checking coverage in nonlinear docs. And frankly, they suck.
ReplyDeleteYep, the help / documentation sucks. Not as nice as it used to be back in the Borland days.
ReplyDeleteI've given up reporting doc issues. There are too many of them. The process is too costly. Now if they made it a public editable wiki... Anyway https://www.google.com/search?q=%22+TComponent+is+the+common+ancestor+of+all+component+classes.%22+site%3Adocwiki.embarcadero.com&filter=0 (I removed the old link as it was way too long)
ReplyDeleteJeroen Wiert Pluimers Are you aware that as an MVP you can get write access to the docwiki? Just contact Kris Houser.
ReplyDeleteUwe Raabe in the past even when I was MVP, I had to re-ask for every new version. Is that restriction gone?
ReplyDeleteFor instance, I came across this topic yesterday: http://docwiki.embarcadero.com/RADStudio/XE7/en/JSON
ReplyDeleteNow, I wanted to point out to somebody that the example code used badly misleading lifetime management.
LJSONObject := nil;
try
LJSONObject := TJsonObject.Create;
....
finally
LJSONObject.Free;
end;
should be
LJSONObject := TJsonObject.Create;
try
....
finally
LJSONObject.Free;
end;
This mistake is made repeatedly. And presumably elsewhere. Given how fundamental JSON is, it seems to me quite important that topics like this are done well. So, I attempted to add something to the talk page. Could I do so? Not I could not.
There is a huge community of developers willing to help. MSDN has allowed user contributions for as long as I can remember. If Emba let us, we could make their product better. We would do it for free.
Marco Cantù
David Heffernan One would like to expect that a help topic would be helpful. ;) Sadly, this is often not the case. I have seen many in which the help is no more illuminating than the name of the method. And others in which the example (and often there is no example) is so trivial as to be of no further illumination.
ReplyDeleteProofreading a linear text is time-consuming, but fairly straightforward. Proofreading a help file, on the other hand, is much less straightforward. You can either print the thing out (usually a terrible option as most will yield one page per oh so short entry), and proof it as a linear flow, or you can navigate the help, attempting to be sure of complete coverage -- good luck with that.
My impression of much of what I have seen in HTML help is that it may have been reviewed to ensure there is text in each topic, but rarely if ever for the actual clarity and quality of the content.
Up through Delphi 7, the manuals were exemplary for their coverage, clarity, and quality. In the twelve years since the release of D7, the help files which are supposed to replace those fine manuals have never come close to being comparable at any level.
As I think I mentioned in another post on documentation, it is a part of the perceived value of any software tool. And in a time when the tools are becoming ever larger and more capable (and complex), a significant part of the product's value is lost -- or at least hidden -- through lack of equally fine documentation.
David Heffernan I don't see what's wrong with the lifetime management, can you elaborate?
ReplyDeleteAsbjørn Heid The code as written in the example will not leak, and will work as intended. But it's an anti-pattern. It should be written the way I showed in my comment above.
ReplyDeleteIt is a bad example to set newer Delphi programmers that one might need to initialise a variable to nil before assigning to it.
David Heffernan Well, I prefer the way written, because it's easier to extend in a safe way.
ReplyDeleteThat being said, I'm not entirely sure why it's an object and not something managed...
ReplyDeleteDavid Heffernan Fixed!
ReplyDeleteAsbjørn Heid How is it easier to extend safely?
ReplyDeleteUwe Raabe That's one. But NOT the one which was the original topic of this post.
ReplyDeleteUwe Raabe Thank you. The deeper problem remains though. It's too hard for us non-MVPs to help. So we don't. If we could help, then the product quality would be improved.
ReplyDeleteDavid Heffernan Well what if you want two json objects? To do it safely with your method you need to nest two try/finally's.
ReplyDeleteWith the way it was written, which I prefer, you simply add another variable, nil both before try/finally, create both inside try and free both in the finally.
Asbjørn Heid I'm fine with nesting two try blocks. Once it gets beyond that then it becomes a problem.
ReplyDeleteBill Meyer If you are going to write the missing documentation I am willing to put it into the docwiki.
ReplyDeleteDavid Heffernan Well, I prefer as little nesting as possible, find it harder to read.
ReplyDeleteAnyway, as I said, I really think the json stuff should be managed.
Asbjørn Heid It is managed to a degree. The root object is the only one you need to destroy. I suppose were an interface used then it would lead to cleaner code. On mobile of course ARC deals with that concern.
ReplyDeleteUwe Raabe Refer to my long comment. Documentation is part of what I pay for in the license. Even so, I would be pleased to write it, had I the experience in that area. I do not -- rather, like Kerry, I am interested in learning that area.
ReplyDeleteDavid Heffernan My first thought when I saw it was "oh this must have been written for mobile". I just couldn't believe they'd gone for the semi-managed route.
ReplyDeleteMaybe we should be more proactive and persuade developers to sign a petition to open up the docs and send it to the company. I used to have write access to fix typos etc when xe2 came, the docs were much worse then. But it wasn't renewed in subsequent releases but I think I still have access to the talk page where I sometimes point out errors. It would be far better however if they opened it up to willing contributors. The alternative is create our own community doc project, start by cloning the existing docs.
ReplyDeleteHerbert Sauro Cloning the existing docs would be a copyright violation.
ReplyDeleteSo judging by the failure of anyone here to address the original topic, I guess we can assume no one here has used the component?
ReplyDeleteDavid Heffernan , Asbjørn Heid
ReplyDeleteWhat about
LJSONObject := nil;
....
....
....
if condition
try
LJSONObject := TJsonObject.Create;
....
finally
LJSONObject.Free;
end;
end;
if LJSONObject <> nil then
.........
So Assigning an un-managed variable to nil first is not a good practice?
Bill Meyer Agreed, but what would Embarcadero do, sue its customers for improving its own product?
ReplyDelete+Sam The original code doesn't do that. I'd also very much question anyone ever writing code like that. Testing the reference against nil after it has been freed?
ReplyDeleteDavid Heffernan Well, I have to admit that codes are weird. However, you can change finally to catch, I mean not to free it, if you want.
ReplyDeleteWhat I really want to say is ALWAYS setting un-managed variable to nil from the beginning and later MAY test against nil is the bad practice?
Try searching for TDSRESTWebDispatcher in the main help. I found some info here: http://docwiki.embarcadero.com/RADStudio/XE8/en/DataSnap_REST_Application_Wizard (or look at the XE7 page if you can't access XE8 page).
ReplyDeleteDatabase is an area where we are understaffed but working hard to catch up. If you want to contribute to the docwiki, just click Help Feedback link at the bottom of any help or docwiki page, and make your request (for example, you can ask for access to the XE8 docwiki). We would appreciate real assistance from the Delphi community.
The class page now contains rather minimal help derived from source code comments:
"WebBroker component that dispatches DataSnap REST requests."
Kris Houser Thanks for your reply, but I do not even have permission to read the page for the link you posted. Might be because, I don't know, XE8 isn't out. Just a thought.
ReplyDeleteLike Bill Meyer said, I guess nobody has used this component since nobody has responded. I finally figured out how to make it work with a lot of trial and error.
ReplyDeleteKerry Sanders write a G+ post on the steps you needed to get it working (:
ReplyDeleteJeroen Wiert Pluimers I will try to do that today.
ReplyDeleteKerry Sanders Yes, XE8 is in Beta right now, so the XE8 docwiki exists but is restricted. Typically, Beta testers ask for and receive permission to access the XE8 docwiki. For the link that I gave, you can view the public XE7 page:
ReplyDeletehttp://docwiki.embarcadero.com/RADStudio/XE7/en/DataSnap_REST_Application_Wizard
This page has no substantive changes for XE8.
The problem, Michael Thuma, is that it is rather difficult to debug something when you do not know how to use the component to start with and there is no documentation to help you get started. There are so many useful things in Delphi that many probably do not know about or do not use at all, because there is no useful documentation for it. That is where Embarcadero is severely lacking. I am sure that Marco Cantù has heard this before also.
ReplyDelete