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?
I guess the arguments for having it at the file level are, one, that
it will be the first thing people if and when they open the source
file; two, programs 'require' the file rather than the class directly,
so it is in the file that the overall functionality provided by the
'require' statement should be documented; and three, some files might
provide core functionality through more than one main class, in which
case the overall functionality really should go in the file, and this
location should be kept consistent even for file with one main class.
The arguments for having it at the class level are, one, that this
matches the usage of Javadoc, and people may be expecting this usage
to be followed in Ruby (not a very strong argument, I admit); two, it
is the class that users actually deal with and come across references
to in code, not (so much) the file; and three, the actual
functionality is provided most directly by the class, not the file.
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.
William
|
