Minero Aoki | 1 Aug 14:42 2003
Picon

Re: First attempt at converting RD->RDoc: net/http.rb

Hi,

  In mail "First attempt at converting RD->RDoc: net/http.rb"
    William Webber <wew <at> williamwebber.com> wrote:

> Gavin suggested I should have a go at converting the
> documentation in one of the standard library classes from RD
> to RDoc format, then post it here to get feedback on style
> etc..  I've done net/http.rb.  I've also extended,
> corrected, and clarified (I hope!) the documentation from
> the original.

Thank you very much!!  It seems really nice.
I'm going to commit your work to the repository.

Regards,
Minero Aoki

Gavin Sinclair | 1 Aug 15:27 2003
Picon

Re: First attempt at converting RD->RDoc: net/http.rb

On Friday, August 1, 2003, 10:42:58 PM, Minero wrote:

> Hi,

>   In mail "First attempt at converting RD->RDoc: net/http.rb"
>     William Webber <wew <at> williamwebber.com> wrote:

>> Gavin suggested I should have a go at converting the
>> documentation in one of the standard library classes from RD
>> to RDoc format, then post it here to get feedback on style
>> etc..  I've done net/http.rb.  I've also extended,
>> corrected, and clarified (I hope!) the documentation from
>> the original.

> Thank you very much!!  It seems really nice.
> I'm going to commit your work to the repository.

You beat me to it!

Thanks, William.

Cheers,
Gavin

William Webber | 3 Aug 15:55 2003

RDoc for net/imap.rb

Hi all!

I've finished converting net/imap.rb from RD to RDoc.  I've
extended the documentation somewhat, with the goal of making
it possible for a user to use it for basic functionality
without having to refer to the RFC.  Note that some of the
documentation features will only work with the cvs version
of rdoc, in particular the documentation of constants and
structs, and the exclusion of the standalone methods at the
end of the file.  Please find the file attached.

Again, comments would be most welcome!

I've CC'ed this to Shugo Maeda, who is (I believe) the
maintainer of net/imap.rb.

Regards,

William
# = net/imap.rb
#
#--
# Copyright (C) 2000  Shugo Maeda <shugo <at> ruby-lang.org>
#
# This library is distributed under the terms of the Ruby license.
# You can freely distribute/modify this library.
#++
#
(Continue reading)

Gavin Sinclair | 3 Aug 18:38 2003
Picon

Re: RDoc for net/imap.rb

On Sunday, August 3, 2003, 11:55:49 PM, William wrote:

> Hi all!

> I've finished converting net/imap.rb from RD to RDoc.  I've
> extended the documentation somewhat, with the goal of making
> it possible for a user to use it for basic functionality
> without having to refer to the RFC. [...]

Excellent.

> Again, comments would be most welcome!

I notice a lot of methods and classes are not documented.  If this is
by design, as I expect, then a :nodoc: directive would reduce clutter
in the rdoc output.  This goes for html.rb as well.

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.

Otherwise, the generated documentation looks fantastic.  There's so
much there it's incredible!  And, at first skim, it's all useful,
readable stuff.

I'll leave these comments for discussion for now and check it in later
on, unless Shugo Maeda gets in first.

Cheers,
Gavin
(Continue reading)

William Webber | 4 Aug 03:04 2003

Re: RDoc for net/imap.rb

On Mon, Aug 04, 2003 at 02:38:48AM +1000, Gavin Sinclair wrote:
> 
> I notice a lot of methods and classes are not documented.  If this is
> by design, as I expect, then a :nodoc: directive would reduce clutter
> in the rdoc output.  This goes for html.rb as well.

OK, I'll look at that.

> 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.

Thanks for the suggestions,

William

Gavin Sinclair | 4 Aug 06:25 2003
Picon

Re: RDoc for net/imap.rb

For want of a better medium (my email access at work is crippled, so
excuse me for tacking onto this thread) ...

William,

I noticed that net/telnet.rb is a pretty easy target for some RDoc, so I
can do it in my limited spare time, and I'd like to reciprocate the effort
you're putting in so we can get it all done sooner.

So can I reserve that one?  If you happen to have already started on it,
then just let me know.

Cheers,
Gavin

William Webber | 4 Aug 14:41 2003

Re: RDoc for net/imap.rb

On Mon, Aug 04, 2003 at 12:25:28AM -0400, Gavin Sinclair wrote:
> 
> I noticed that net/telnet.rb is a pretty easy target for some RDoc, so I
> can do it in my limited spare time, and I'd like to reciprocate the effort
> you're putting in so we can get it all done sooner.
> 
> So can I reserve that one?

NO!  They're all MINE!  MINE, I tell you!

:-)

That'd be great.  I'll move on to net/pop.rb next.  Like the
other files maintained by Minero Aoki, the RD is very
complete, so it'll just be a matter of converting it to
RDoc.

Anyone want to grab net/smtp.rb before it goes?  It's also
by Minero Aoki, so it should just be a matter of converting
to RDoc and checking it over quickly.  Then we'll have
finished off the net package (except for net/protocol.rb,
the status of which I'm unsure about).

William

William Webber | 4 Aug 15:26 2003

Re: RDoc for net/imap.rb

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.
(Continue reading)

Gavin Sinclair | 4 Aug 15:28 2003
Picon

Re: RDoc for net/imap.rb

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.

(Continue reading)

Gavin Sinclair | 4 Aug 15:49 2003
Picon

Re: RDoc for net/imap.rb

On Monday, August 4, 2003, 11:28:18 PM, Gavin wrote:

> I submitted some code, James submitted a bug report, then I got busy
> with life, work, and http://vim-ruby.rubyforge.net.

That should be http://vim-ruby.rubyforge.org, of course...


Gmane