Questions About Documenting erb.rb

[James Edward Gray II]

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

 

[gabriele renzi]

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]

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]

James Edward Gray II ha scritto:

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 Edward Gray II]

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]

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 Edward Gray II]

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