Forum: Ruby Documentation conventions

Hi there,
I've been searching the web for some time now, but I can't find any
reasonable conventions on how to write Ruby documentations. There are
some pages out there describing what's the best way to write Ruby source
code, but if they cover documentation, they do it in just a very raw
way, not going into depth.
Instead, I've found other Ruby documentation tools, such as NaturalDocs
and YARDOC, but I'm not convinced by any of them, because NaturalDocs
doesn't has any avantages over the usual RDoc (I think) and YARDOC seems
to have problems with non-ASCII characters and is therefore useless if I
want to or have to document my code in another language than English. So
far, I've been happy with the markup RDoc provides (besides the fact
that it doesn't support nested lists :( ). Also, I want my documentation
to be readable if someone *does not* have a specific documentation tool
beside RDoc installed.
But there is this simple question: What are the documentation
conventions that are used by wide parts of the Ruby community (*NOT* the
Rails community)? Can anybody point me somewhere?

If not, I'd be happy to work out some "reference document", or however
to call that, which states which way documenting should go.

Thoughts?
Marvin

Marvin Gülker wrote:
> Hi there,
> I've been searching the web for some time now, but I can't find any
> reasonable conventions on how to write Ruby documentations. There are
> some pages out there describing what's the best way to write Ruby source
> code, but if they cover documentation, they do it in just a very raw
> way, not going into depth.

Look at the libraries you're using.  You'll see that virtually everybody 
uses RDoc.  Problem solved.

Best,
-- 
Marnen Laibow-Koser
http://www.marnen.org
marnen@marnen.org

Marnen Laibow-Koser wrote:
> Marvin Gülker wrote:
>> Hi there,
>> I've been searching the web for some time now, but I can't find any
>> reasonable conventions on how to write Ruby documentations. There are
>> some pages out there describing what's the best way to write Ruby source
>> code, but if they cover documentation, they do it in just a very raw
>> way, not going into depth.
> 
> Look at the libraries you're using.  You'll see that virtually everybody 
> uses RDoc.  Problem solved.
> 
> Best,
> -- 
> Marnen Laibow-Koser
> http://www.marnen.org
> marnen@marnen.org

That's true, but I've also read at more than one time that the 
documentation of many libraries is not sufficient, because they don't 
contain enough information. I've been pointed to YARDOC when I asked, 
but that doesn't fit my needs as I stated already (maybe I simply 
dislike that @ tags :) )

Marvin

Marvin Gülker wrote:
> Marnen Laibow-Koser wrote:
>> Marvin Gülker wrote:
>>> Hi there,
>>> I've been searching the web for some time now, but I can't find any
>>> reasonable conventions on how to write Ruby documentations. There are
>>> some pages out there describing what's the best way to write Ruby source
>>> code, but if they cover documentation, they do it in just a very raw
>>> way, not going into depth.
>> 
>> Look at the libraries you're using.  You'll see that virtually everybody 
>> uses RDoc.  Problem solved.
>> 
>> Best,
>> -- 
>> Marnen Laibow-Koser
>> http://www.marnen.org
>> marnen@marnen.org
> 
> That's true, but I've also read at more than one time that the 
> documentation of many libraries is not sufficient, because they don't 
> contain enough information. 

So write the extra information.  This a docs-writing issue, not a 
technological one.

> I've been pointed to YARDOC when I asked, 
> but that doesn't fit my needs as I stated already (maybe I simply 
> dislike that @ tags :) )
> 
> Marvin

Best,
-- 
Marnen Laibow-Koser
http://www.marnen.org
marnen@marnen.org