[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

Short introduction on how to create good source doc?

Joshua Muheim

11/19/2007 1:46:00 PM

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

Phrogz

11/19/2007 2:31:00 PM

0

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

which produces:
http://phrogz.net/RubyLibs/rdoc/files/Ourobor...
http://phrogz.net/RubyLibs/rdoc/classes/Ouro...
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

11/19/2007 6:00:00 PM

0

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/Ou...
>
> which produces:
> http://phrogz.net/RubyLibs/rdoc/files/Ourobor...
> http://phrogz.net/RubyLibs/rdoc/classes/Ouro...
> 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

11/19/2007 7:13:00 PM

0

Dejan Dimic wrote:
> On Nov 19, 3:31 pm, Phrogz <phr...@mac.com> wrote:
>> http://phrogz.net/RubyLibs/rdoc/classes/Ouro...
>> 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-....

Phrogz

11/20/2007 3:01:00 AM

0

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

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/