[rdoc] sections-patch

[Michael Neumann]

Hi,

With the patch below, it's possible to wrap :section: tags like this:

# - - - - - - - - - - - - - - - - - -
# :section: Section-header
# - - - - - - - - - - - - - - - - - -

Regards,

Michael


RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup.rb,v
retrieving revision 1.2
diff -r1.2 simple_markup.rb
306a307,312

if /^(-\s){3,}/ =~ active_line
line.stamp(Line::BLANK, 0)
return
end

Index: lib/rdoc/parsers/parse_rb.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/parsers/parse_rb.rb,v
retrieving revision 1.35
diff -r1.35 parse_rb.rb
2313c2313
< context.set_current_section(param, comment)
---

context.set_current_section(param, (comment =~

/:section.*)\n/m) ? $1 : comment)

 

[Dave Thomas]

Hi,

With the patch below, it's possible to wrap :section: tags like this:

# - - - - - - - - - - - - - - - - - -
# :section: Section-header
# - - - - - - - - - - - - - - - - - -

Michael:

I've done something that has the same effect, but which I think is more
general.

You can now have any number of lines before :section: in the comment
block. These will be stripped from the output. In addition, if the same
lines appear at the end of the block, they'll be ignored to.

This means that

# :section: My Section
# This is the section
# that I wrote

# ---------------------------------
# :section: My Section
# This is the section
# that I wrote
# ---------------------------------

and

# SECTION SECTION SECTION
# !!!! !!!! !!!! !!!!
# :section: My Section
# This is the section
# that I wrote
# SECTION SECTION SECTION
# !!!! !!!! !!!! !!!!

will all generate the same output.

I've checked the change into the 1.8 and 1.9 HEADs


Cheers

Dave

 

[Michael Neumann]

Michael:

I've done something that has the same effect, but which I think is more
general.
Great!

You can now have any number of lines before :section: in the comment
block. These will be stripped from the output. In addition, if the same
lines appear at the end of the block, they'll be ignored to.

How about this idea:

Lines before a section are handled as usual (how would they be handled?
Probably best would be to ignore them). Lines after the section are
included in the section description. Lines with two ## in front are ignored.

This would allow:

# :section: My Section
# Description of My Section...
# ...

or:

## This is an rdoc comment
##---------------------------------------------
# :section: My Section
# Description of My Section
##---------------------------------------------

The description (if given) would be included in the Contents and after
each Section-header.

What do you think?

Regards,

Michael

 

[Dave Thomas]

Lines before a section are handled as usual (how would they be
handled? Probably best would be to ignore them). Lines after the
section are included in the section description. Lines with two ## in
front are ignored.

What do you think?

I'm not sure I see the benefit, but I'm probably being dense today. I
was aiming for a solution that would meet your original requirement,
but that would also be fairly natural to use and unobtrusive in the
user's source code.

Cheers

Dave

 

[Michael Neumann]

I'm not sure I see the benefit, but I'm probably being dense today. I
was aiming for a solution that would meet your original requirement, but
that would also be fairly natural to use and unobtrusive in the user's
source code.

I am totally happy with your current implementation. I only thought,
that sometimes it would be nice to describe the sections.

Now I've another idea ;-)

Collect all sections (of all files) and display them similar as the
"Files", "Classes" and "Methods" pane. For each section display all
methods that are in this section (of all classes).

But that's only a brief idea, nothing concrete...

Thanks so far.

Regards,

Michael

 

[Dave Thomas]

I am totally happy with your current implementation. I only thought,
that sometimes it would be nice to describe the sections.

You can do that (and the description appears under the section in the
output). The recent patch allows you to add your separator lines before
and after the description.

Collect all sections (of all files) and display them similar as the
"Files", "Classes" and "Methods" pane. For each section display all
methods that are in this section (of all classes).

Absolutely - that's in the plans. But first, I have to see if people
actually use the section idea. If it takes off, then I'll add lots of
different bells and whistles for it. If not, then I won't clutter the
code with extra stuff


Cheers

Dave

 

[Michael Neumann]

You can do that (and the description appears under the section in the
output). The recent patch allows you to add your separator lines before
and after the description.



Absolutely - that's in the plans. But first, I have to see if people
actually use the section idea. If it takes off, then I'll add lots of
different bells and whistles for it. If not, then I won't clutter the
code with extra stuff

Sure. What is even more useful IMO, is the ability to group
classes/modules into sections, not just methods. Looking at some rdoc
documentations, you see lots of classes, but don't see their
relationship. If all this information is available, one could write a
dynamic CGI-application, that behaves similar as a smalltalk class
browser... similar to ri but much more powerful.

Regards,

Michael

 

[Werner Maier]

Sure. What is even more useful IMO, is the ability to group
classes/modules into sections, not just methods. Looking at some rdoc
documentations, you see lots of classes, but don't see their
relationship. If all this information is available, one could write a
dynamic CGI-application, that behaves similar as a smalltalk class
browser... similar to ri but much more powerful.

Regards,

Michael

yes, sure


Werner