Documentation conventions

[Marvin Gülker]

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

 

[Marnen Laibow-Koser]

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
(e-mail address removed)

 

[Marvin Gülker]

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
(e-mail address removed)

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

 

[Marnen Laibow-Koser]

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
(e-mail address removed)