What's the most common way for including a howto/documentation in a ruby-gem?

Question

I saw that if the gem is installed also the rdoc is generated and you can access the rdoc by

gem server #->localhost:8808

I am thinking of the most common ways how to describe a ruby-developer how to use the gem that was installed. Where i am coming from (java) the apidocs/howtos e.g. are already included in the jars.

I saw that there is a kind of README.rdoc file -convention(?) and thought maybe that's where the ruby-developer will start looking after downloading a gem?

Answer 1

It depends on the developer.

If the README is heavily marked up (e.g., lots of Markdown or RDoc) it's often most convenient to use gem server to access the Gem documentation from a local gem doc server.

Or follow the www link in the gem server listing, or read the file manually.

Additional documentation source is generally included in the doc directory, built using normal Ruby tools (rake and/or rdoc).

I'm not entirely sure what you're asking, though. First, Java libraries generally don't include the API docs or source, they're generally bundled separately, particularly if you're using Maven. Gems include the source, so RDoc can always be generated.

In Java, examples are only present if (a) the developer (IMO abuses) Javadocs by including the examples in the API docs, or (b) examples are included in the source and you have the source. It's rare there are "howtos" in a downloaded Java library, unless it was developed using Maven, you package the site, and the site includes usage pages beyond the normal API reports.