Short introduction on how to create good source doc?

ruby-talk
1

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

···

--
Posted via http://www.ruby-forum.com/.

2

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

which produces:
  File: Ouroboros.rb
  Class: Ouroboros
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.)

···

On Nov 19, 6:46 am, Joshua Muheim <fo...@josh.ch> wrote:

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?

3

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.

···

On Nov 19, 3:31 pm, Phrogz <phr...@mac.com> wrote:

On Nov 19, 6:46 am, Joshua Muheim <fo...@josh.ch> wrote:

> 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:
File: Ouroboros.rb
Class: Ouroboros
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.)

4

Dejan Dimic wrote:

···

On Nov 19, 3:31 pm, Phrogz <phr...@mac.com> wrote:

Class: Ouroboros
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.

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...
--
Posted via http://www.ruby-forum.com/\.

5

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/

···

On Nov 19, 12:12 pm, Joshua Muheim <fo...@josh.ch> wrote:

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...