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


 

Forums >

comp.lang.ruby

Questions About Documenting erb.rb

James Gray

10/26/2004 6:18:00 PM

I'm currently trying to document erb.rb and this is my first big foray
into RDoc land. erb.rb has code like this:

class ERB
# ...
end

class ERB
# ...
end

class ERB
# ...
end

As near as I can determine, RDoc picks up the comment before the FINAL
class definition to use in the documentation. Here are my questions
about that:

1. Can I override this somehow? It seems odd to me to shove all the
documentation down to almost the bottom of the source.

2. As a documentation writer, I assume my job is to affect the
original source as little as humanly possible. (I'm even trying very
hard to preserve the few comments that are there, though they aren't
documentation material.) Given this, is a switch to:

class ERB
# ...

# ...

# ...
end

overstepping my role? I don't feel right about it, but I would like to
hear the opinions of others.

(Note: I do not believe the above would affect erb.rb syntax in any
way. Please correct me if I'm wrong!)

Thanks.

James Edward Gray II
6 Answers

gabriele renzi

10/26/2004 7:06:00 PM

0

James Edward Gray II ha scritto:
> I'm currently trying to document erb.rb and this is my first big foray
> into RDoc land. erb.rb has code like this:

just a note: have you joined the ruby-doc mailing list? it should be the
place to coordinate and direct documentation efforts.
See ruby-doc.org for details

Dave Thomas

10/26/2004 9:40:00 PM

0


On Oct 26, 2004, at 13:17, James Edward Gray II wrote:

> As near as I can determine, RDoc picks up the comment before the FINAL
> class definition to use in the documentation. Here are my questions
> about that:
>
> 1. Can I override this somehow? It seems odd to me to shove all the
> documentation down to almost the bottom of the source.

Why not move the documentation to the top? If there's no documentation
before a class body, RDoc won't replace existing.

Cheers

Dave

Dave Thomas

10/26/2004 9:41:00 PM

0


On Oct 26, 2004, at 14:09, gabriele renzi wrote:

> James Edward Gray II ha scritto:
>> I'm currently trying to document erb.rb and this is my first big
>> foray into RDoc land. erb.rb has code like this:
>
> just a note: have you joined the ruby-doc mailing list? it should be
> the place to coordinate and direct documentation efforts.
> See ruby-doc.org for details

If it's an RDoc question, it's probably best asked here. I'm not on the
ruby-doc list.


Cheers

Dave

James Gray

10/26/2004 10:18:00 PM

0

On Oct 26, 2004, at 4:40 PM, Dave Thomas wrote:

> Why not move the documentation to the top? If there's no documentation
> before a class body, RDoc won't replace existing.

The author has some simple comments before each class I'm trying not to
tamper with.

If I get it to ignore all those will it keep the first comment?

If so, how could I do that? Proceed them all with a

#--

?

Thanks for the tips.

James Edward Gray II

Gavin Kistner

10/27/2004 2:34:00 PM

0

On Oct 26, 2004, at 4:17 PM, James Edward Gray II wrote:
> The author has some simple comments before each class I'm trying not
> to tamper with.
>
> If I get it to ignore all those will it keep the first comment?
>
> If so, how could I do that? Proceed them all with a
>
> #--

Does this help?

#--
# Author's file comments
# go here
# and so on
#++
# RDoc is so cool! Here is
# my documentation for the file.


#--
# Author's class comments
#++
# My documentation for the class.
class Foo

#--
# Author's method comments
#++
# My documentation for the method
def foo
#...
end

#--
# Author's method comments
#++
# My documentation for the method
def bar
#...
end

end

#--
# Author's class comments
#++
# My documentation for the class.
class Bar

#--
# Author's method comments
#++
# My documentation for the method
def foo
#...
end

#--
# Author's method comments
#++
# My documentation for the method
def bar
#...
end

end

James Gray

10/27/2004 6:36:00 PM

0

On Oct 27, 2004, at 9:34 AM, Gavin Kistner wrote:

> Does this help?
>
> #--
> # Author's file comments
> # go here
> # and so on
> #++
> # RDoc is so cool! Here is
> # my documentation for the file.

Yeah, that's pretty much what I figured out, with the previous pointer
from Dave to guide me. I put my documentation comments before the
first class, then proceeded all of the author's later comments with a:

#--

That was enough to keep RDoc from replacing them.

Thanks for the help.

James Edward Gray II