beginner instructions on how to create rdoc documentation

Can anybody recommend some documentation for a first-time
ruby documentation 
writer?  So far, all I've found is sample documented code.

For the time being, I'm only planning on working on adding
rdoc to ruby code, 
not to stuff written in C.

On Jul 22, 2007, at 1:33 AM, Brian Sammon wrote:
> Can anybody recommend some documentation for a
first-time ruby  
> documentation
> writer?  So far, all I've found is sample documented
code.

Have you seen this yet?

htt
p://ruby-doc.org/documentation-guidelines.html

> For the time being, I'm only planning on working on
adding rdoc to  
> ruby code,
> not to stuff written in C.

The process is largely the same so feel free to give C a try
too,  
once you get comfortable.
-Mat

On Jul 22, 2007, at 1:33 AM, Brian Sammon wrote:
> Can anybody recommend some documentation for a
first-time ruby  
> documentation
> writer?  So far, all I've found is sample documented
code.

Have you seen this yet?

htt
p://ruby-doc.org/documentation-guidelines.html

> For the time being, I'm only planning on working on
adding rdoc to  
> ruby code,
> not to stuff written in C.

The process is largely the same so feel free to give C a try
too,  
once you get comfortable.
-Mat

> > Can anybody recommend some documentation for a
first-time ruby  
> > documentation
> > writer?  So far, all I've found is sample
documented code.
> 
> Have you seen this yet?
> 
> htt
p://ruby-doc.org/documentation-guidelines.html

I have.  It's not really what I had in mind.  I'm hoping
there's another page 
that I missed.

Or I could go at this from another angle:
I'm trying to start using the httpclient package (http://raa.ruby-lang.or
g/proj
ect/http-access2/).  When I ran rdoc to generate the
documentation, I found 
the generated documentation to be incomplete, particularly
in regards to 
HTTPClient, the main class.  So I decided to submit a patch
to the httpclient 
author containing improved documentation.

But when I look at the httpclient source code and compare it
to the generated 
rdoc pages, I can't figure out what logic rdoc is using. 
There are a lot of 
comments and a lot of methods in the source code that don't
turn up in the 
rdoc output.  There's a few places where ':nodoc:' appears,
but not enough to 
explain the disparity (at least to me).

So I'm seeking a [better|any] understanding of how rdoc
works.

I contacted the author of httpclient about this yesterday,
and I haven't heard 
back from him yet.

> > Can anybody recommend some documentation for a
first-time ruby  
> > documentation
> > writer?  So far, all I've found is sample
documented code.
> 
> Have you seen this yet?
> 
> htt
p://ruby-doc.org/documentation-guidelines.html

I have.  It's not really what I had in mind.  I'm hoping
there's another page 
that I missed.

Or I could go at this from another angle:
I'm trying to start using the httpclient package (http://raa.ruby-lang.or
g/proj
ect/http-access2/).  When I ran rdoc to generate the
documentation, I found 
the generated documentation to be incomplete, particularly
in regards to 
HTTPClient, the main class.  So I decided to submit a patch
to the httpclient 
author containing improved documentation.

But when I look at the httpclient source code and compare it
to the generated 
rdoc pages, I can't figure out what logic rdoc is using. 
There are a lot of 
comments and a lot of methods in the source code that don't
turn up in the 
rdoc output.  There's a few places where ':nodoc:' appears,
but not enough to 
explain the disparity (at least to me).

So I'm seeking a [better|any] understanding of how rdoc
works.

I contacted the author of httpclient about this yesterday,
and I haven't heard 
back from him yet.

On Jul 22, 2007, at 2:12 PM, Brian Sammon wrote:
> Or I could go at this from another angle:
> I'm trying to start using the httpclient package (http://raa.ruby- 
> lang.org/proj
> ect/http-access2/).  When I ran rdoc to generate the
documentation,  
> I found
> the generated documentation to be incomplete,
particularly in  
> regards to
> HTTPClient, the main class.  So I decided to submit a
patch to the  
> httpclient
> author containing improved documentation.
>
> But when I look at the httpclient source code and
compare it to the  
> generated
> rdoc pages, I can't figure out what logic rdoc is
using.  There are  
> a lot of
> comments and a lot of methods in the source code that
don't turn up  
> in the
> rdoc output.  There's a few places where ':nodoc:'
appears, but not  
> enough to
> explain the disparity (at least to me).
>
> So I'm seeking a [better|any] understanding of how rdoc
works.
>
> I contacted the author of httpclient about this
yesterday, and I  
> haven't heard
> back from him yet.

This might help some if you haven't already found it:
http:/
/www.ruby-doc.org/core/classes/RDoc.html

I'm no rdoc expert myself, so I can't say why you're not
seeing the  
comments.  Maybe the author of the package can help some.
-Mat

On Jul 22, 2007, at 2:12 PM, Brian Sammon wrote:
> Or I could go at this from another angle:
> I'm trying to start using the httpclient package (http://raa.ruby- 
> lang.org/proj
> ect/http-access2/).  When I ran rdoc to generate the
documentation,  
> I found
> the generated documentation to be incomplete,
particularly in  
> regards to
> HTTPClient, the main class.  So I decided to submit a
patch to the  
> httpclient
> author containing improved documentation.
>
> But when I look at the httpclient source code and
compare it to the  
> generated
> rdoc pages, I can't figure out what logic rdoc is
using.  There are  
> a lot of
> comments and a lot of methods in the source code that
don't turn up  
> in the
> rdoc output.  There's a few places where ':nodoc:'
appears, but not  
> enough to
> explain the disparity (at least to me).
>
> So I'm seeking a [better|any] understanding of how rdoc
works.
>
> I contacted the author of httpclient about this
yesterday, and I  
> haven't heard
> back from him yet.

This might help some if you haven't already found it:
http:/
/www.ruby-doc.org/core/classes/RDoc.html

I'm no rdoc expert myself, so I can't say why you're not
seeing the  
comments.  Maybe the author of the package can help some.
-Mat