Questions About Documenting erb.rb

ruby-talk
1

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

2

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

3

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

Cheers

Dave

···

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.

4

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

Cheers

Dave

···

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

5

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

···

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.

#--

?

Thanks for the tips.

James Edward Gray II

6

Does this help?

···

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

#--

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

7

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:

···

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.

#--

That was enough to keep RDoc from replacing them.

Thanks for the help.

James Edward Gray II