Short introduction on how to create good source doc?

[Joshua Muheim]

Hi all

I'd like to document my Ruby sources in a clean and standardized way.
But I couldn't find a short introduction on how to do that, e.g. what
markup tags to use etc.? Anyone can post me a link or two?

Thanks
Josh

 

[Phrogz]

I'd like to document my Ruby sources in a clean and standardized way.
But I couldn't find a short introduction on how to do that, e.g. what
markup tags to use etc.? Anyone can post me a link or two?

I think I use RDoc markup well and consistently in this file:
http://phrogz.net/RubyLibs/Ouroboros.rb

which produces:
http://phrogz.net/RubyLibs/rdoc/files/Ouroboros_rb.html
http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html
when run through RDoc.

Basically, if you want to document your code in a standard way, find a
file whose documentation you think is good and follow its conventions.
Just view the source of the ruby file. (Not HTML.)

 

[Dejan Dimic]

I think I use RDoc markup well and consistently in this file:http://phrogz.net/RubyLibs/Ouroboros.rb

which produces:
http://phrogz.net/RubyLibs/rdoc/files/Ouroboros_rb.html
http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html
when run through RDoc.

Basically, if you want to document your code in a standard way, find a
file whose documentation you think is good and follow its conventions.
Just view the source of the ruby file. (Not HTML.)

Just to add a little observation.
When writing documentation it's beneficial to have as much real life
examples of class and methods usage as you can think of.
It's easer to learn by example.

 

[Joshua Muheim]

Just to add a little observation.
When writing documentation it's beneficial to have as much real life
examples of class and methods usage as you can think of.
It's easer to learn by example.

Thanks for the hint. Because I'm creating Ruby on Rails codes I'd like
to adhere to its documenting conventions. Sadly I don't know where its
sources are. I'm on OS X 10.4 and installed Rails using Ruby Gems...

 

[Phrogz]

Thanks for the hint. Because I'm creating Ruby on Rails codes I'd like
to adhere to its documenting conventions. Sadly I don't know where its
sources are. I'm on OS X 10.4 and installed Rails using Ruby Gems...

Slim2:~ phrogz$ ls -Flag /usr/local/lib/ruby/gems/1.8/gems/ | grep -E
"active|rails"
drwxr-xr-x 10 wheel 340 Oct 19 13:09 activerecord-1.15.5/
drwxr-xr-x 5 wheel 170 Oct 19 13:07 activesupport-1.4.4/
drwxr-xr-x 16 wheel 544 Nov 1 21:58 rails-1.2.5/