After getting frustrated with existing solutions I threw together a
script to wrap comments in my ruby code.  It understands headers,
basic lists, some rdoc formatting, indentation both before and after
the #, passes code through without modification and has some options
for customization.  Full documentations follows.

It can be downloaded from my website at:
  http://www.math.wisc.edu/~alfeld/code/rubywrap/rubywrap.rb
and documentation is also available at
  http://www.math.wisc.edu/~alfeld/code/rubywrap/

Please feel free to send me feedback at this e-mail or the e-mail
below.  I hope some of you find this useful.

----

File: rubywrap.rb
Wraps comments in ruby files.

== License

Copyright (c) 2006 Christopher Alfeld

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.

== Author

Christopher Alfeld (calfeld / math.utah.edu)

Web: http://www.math.wisc.edu/~alfeld/code/rubywrap/

Please feel free to e-mail bugs, questions, comments, etc.

== Description

RubyWrap is a word wrapper utility designed for ruby scripts.  It should,
however work for any programming language which uses an initial prefix for
comments (see --prefix).  RubyWrap correctly handles indented comments,
indented text within comments, header comments, and many forms of lists.  It
will also pass through code without change and detabify.

See Example.

== Example

The following text will all wrap correctly.

 # This a header...
 # ... it will not absorb this line.
 #
 #     This block of text will be left alone by default as it represents
 #     a verbatim block of RDoc text.  If the -n option is given then
 #     RDoc-Style is off then it will be correctly wrapped, maintaining it's
 #     indentation level.  In any case it will not abosrb...
 #  ... this line because this line has a different indentation level.
 #
      # This comment will retain it's indentation and correctly wrap when
      # it goes over over the page width.

 # label  This is a list.  It contains a label and some text.  If the text
 #        is indented past the label and the final space lines up then it
 #        is considered to be a single block and properly wrapped.  Note
 #        that this requires at least two lines to get right.

 # * This is an rdoc list element.  It properly wraps even as a single line
 #   and does not require a second line to wrap correctly.

 # * Here are two rdoc list elements.  Even though they are adjacent...
 # * ... they will not wrap.


== Headers

RubyWrap uses a very simple algorithm for identifying headers: it looks for
short lines.  Any line below a certain threshold is not-wrapped. By default
this threshold is 50, it can be changed with -s.

== Non Rdoc Style

When RDoc style is turned off (-n) RubyWrap identifies list items by looking
for a label and then a second line indented past the label.  This means that
single line list items do not wrap, the second line is required.

Blocks of text indented after the # are wrapped maintaining their
indentation level.

== RDoc Style (Default)

In RDOc style RubyWrap looks for lines that appear to be RDoc list items.
These lines are then properly wrapped with later lines indented properly and
closely set list items do not wrap together.

Text indented after the # is considered to be verbatim and left alone.

RDoc tries to find a natural margin for comments.  RubyWrap currently does
not do this.  If you use more than a single space after your # then you
should redefine the prefix with -p.

== Comment Prefix

The comment prefix can be changed with -p.  By default the comment prefix is
"# ".  Note the trailing space.  You will generally want a trailing space
for any prefix.  If you prefer to indent your comments more than a single
space past the # then change the prefix appropriately.

== Limitations

* Doesn't handle multilevel RDoc lists correctly.  This is a balance between
  recognizing verbatim blocks and list items.  A nice solution would be to
  treat it is a list item if it appeared to be a part of a list but that
  would require context beyond the current block.
* Doesn't find the natural margin like RDoc does.  This can easily be
  overcome by -p but it would be a nice feature.  Probably not too hard.

== Using with other languages

With appropriate use of -r and -p RubyWrap should work for any language that
distinguishes comments by some prefix.  Languages that use "# " should work
well out of the box.

== Usage

rubywrap.rb [<options>]
Options:
  --prefix, -p <prefix>       Use <prefix> as the comment prefix.
  --shortthreshold -s <n>     Lines of length <= n are single line blocks.
  --cols, -c <n>              How many columns to wrap to (default: 78)
  --tabsize, -t <n>           How many spaces a tab is (default: 2)
  --no-rdoc-style, -n         Do not use RDoc conventions.
  --retabify, -r              Retabify output.
  --help, -h                  Display this help.
  --doc, -d                   Display full documentation.
Reads commented code from stdin and outputs wrapped commented code to
stdout.