Re: searching the documentation
Re: searching the documentation
- Subject: Re: searching the documentation
- From: Fritz Anderson <email@hidden>
- Date: Thu, 26 Jan 2006 13:59:38 -0600
On 25 Jan 2006, at 11:07 AM, Philipp Donzé wrote:
From time to time I'd like to inspect the definition of a structure
doing so by "Apple-double clicking" on the word (e.g.
IOUSBDeviceInterface182). This works nicely and takes me right to
the definition. But as it's full of "cryptic comments" which come
from a "documentation system", it's a pain to read.
I had a look at IOKit's version of USB.h, and yes there are HeaderDoc
comments in it. These are written into the headers by the engineers
who write and maintain them, and are used to produce the HTML documents.
1. They constitute about 10% of the file. That's not particularly
intrusive.
2. They are actually informative. Once you know that the @words are
part of the HeaderDoc syntax, having the documentation for the struct
and its members is a Good Thing. They provide more information
than // comments would be likely to provide.
3. Because HeaderDoc makes certain demands on the amount and
organization of the information the comments contain, they encourage
the engineers who write them to write more, and, one hopes, clearer
comments than they otherwise would.
4. Not putting HeaderDoc comments in the file is not to be seriously
considered. Apple has to rely on a documentation generator; the task
of accurately and timely documenting thousands (tens of thousands?
hundreds of thousands?) of elements in hundreds (thousands?) of
headers would otherwise be impossible. The tool requires those
comments to come immediately before the struct or prototype being
documented. Putting them in the production version of the header
assures that the documentation and the delivered header do not get
out of synch.
The alternative might be to pass the headers through a Perl script
that strips all the HeaderDoc comments out, and deliver the result.
But then the header will not be documented in-place for users who
refer to it. There is no alternative (in this world) in which the
HeaderDoc comments are accurately duplicated by conventional comments.
So I suggest that your objection to the HeaderDoc comments is not, on
reflection, reasonable.
So as this is in "documenting tool"-format I expect, when doing a
"option-double click" on the same word, the "Developer
Documentation" comes up displaying the same thing but much nicer...
But: no, the opening window displays "USB.h" which has no reference
or anything related to my search term.
Am I missing some part of the documentation or how do I get this
"option-double clicking" working? Or do I expect too much from this
"documentation tool"?
I put IOUSBDeviceDescriptor into a file and option-double clicked on
it. As you said, the document search displayed the top of the page
"USB.h". The documentation you want is in that page, and is
accessible through the "function" popup at the top of the page panel;
but the intended behavior is that the page be displayed, _and_
scrolled to the structure you opt-double-clicked on. This is a bug...
As I was writing this, an update to the Developer Tools Documentation
came through, fixing this bug.
-- F
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden