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.