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.
FYI, William, shortly before you joined the list we were working on
"rj" ("ri".succ), which is a modified ri to support the standard
library (you do know ri, right? :) I submitted some code, James
submitted a bug report, then I got busy with life, work, and
http://vim-ruby.rubyforge.net. Updates coming soon, I hope.
Anyway, the file/class needs some discussion before committing to one
or the other. Just do file level for now, I suggest.
Gavin
|
