On Mon, 4 Aug 2003 23:28:18 +1000, Gavin Sinclair wrote:
> On Monday, August 4, 2003, 11:26:04 PM, William wrote:
>> On Mon, Aug 04, 2003 at 11:04:30AM +1000, William Webber wrote:
>>> On Mon, Aug 04, 2003 at 02:38:48AM +1000, Gavin Sinclair wrote:
>>>> The "overview" documentation for IMAP (including usage examples) is
>>>> documented at the class level, whereas for HTTP this is done at the
>>>> file level. It would be good to get these consistent.
>>> Ah, good point; a case of not seeing the wood for the trees. I'll
>>> move the IMAP overview documentation from class-level to file-level.
>> Actually, I notice that in net/ftp.rb the overview documentation is at
>> the class level, so perhaps this should be the standard location for
>> it. What do people think?
>> So, what do people think? I still tend towards putting overview
>> documentation at file level, but I'm comfortable either way, and I
>> agree that one choice or the other should be made consistently.
> It's hard for me to come to a conclusion. I sort of angle towards the
> file level as well, with a clear comment on the main class (perhaps
> most/all classes?) that says "For usage information see ...".
>
> One good reason for class level, though, is that the usage information
> will then come out in ri/rj.
A year ago, I talked Dave into adding some new tags to RDoc because it made
it easier for me, and it removed the need for "file-level" documentation. If
you look at my text-format documentation, you'll see these at the beginning
of the source file:
# :title: Text::Format
# :main: Text::Format
These correspond to the appropriate command-line flags (and the command-line
should override these; I haven't really tried that). :main: specifies the
first page that will be shown, thus you could do:
# :main: Net::IMAP
And the documentation generated for Net::IMAP will appear first.
It is *not* clear what will happen if there are multiple, conflicting :main:
tags (if you're generating the documentation for all of net/* at once). Then
again, I don't ever use file-level documentation.
-austin
--
austin ziegler * austin@xxxxxxxxxxxxx * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.08.04
* 10.34.18
|
