Emacs RDoc Fill

Emacs RDoc Fill is an Emacs extension for formatting source code comments. The comments may be either plain text, or text containing RDoc (Ruby Documentation System) style markup. Various comment styles are supported.

An Example

When formatted using Emacs RDoc Fill, this comment

# A messy looking comment
# with some short
# lines and some much much much much much much much much much much much much much much much much much much much much much much much longer lines
# and     weird     spacing
# and some argument declarations.
# first_argument:: This argument should be a very very very very very very very very very very very very long piece of text.
# second_argument:: This must always be a false value.

becomes

# A messy looking comment with some short lines and some much much
# much much much much much much much much much much much much much
# much much much much much much much much longer lines and weird
# spacing and some argument declarations.
# first_argument:: This argument should be a very very very very very
#                  very very very very very very very long piece of
#                  text.
# second_argument:: This must always be a false value.

Dependencies

The library depends on RDoc (tested with version 1.0.1). It is included as standard in recent versions of Ruby, but say on Debian you might need to install it explicitly with

apt-get install rdoc1.8

Another dependency is codeprint.rb, which you must have on the Ruby $LOAD_PATH. codeprint can be downloaded from here.

Installation

Unpack the distribution somewhere, and then tell Emacs where it was unpacked by setting the usc-home variable to point to the lib directory. You must also add usc-home to your Emacs library search path. E.g., you could add the following to your ~/.emacs:

(setq usc-home (concat (getenv "HOME") "/emacs-rdoc-fill/lib"))

(setq load-path
      (nconc
       (list
        usc-home
        )
       load-path))

Then you can use the library to implement commands in Emacs Lisp. E.g.,

(require 'util-shell-commands)

(defun ruby-fill-rdoc-comment ()
  (interactive)
  (usc-filter-ruby-comment-region "fill_rdoc_comment ruby"))

(defun ruby-fill-rdoc-rd-block ()
  (interactive)
  (usc-filter-ruby-rd-region "fill_rdoc_comment none"))

(defun elisp-fill-rdoc-comment ()
  (interactive)
  (usc-filter-lisp-comment-region "fill_rdoc_comment lisp"))

(defun python-fill-docstring ()
  (interactive)
  (usc-filter-python-ds-region "fill_rdoc_comment none,indent"))

You will probably also want to assign key bindings to the commands you create for the relevant Emacs major modes. E.g.,

(add-hook 'emacs-lisp-mode-hook
          (lambda ()
            (define-key emacs-lisp-mode-map [(control o) (f)]
              'elisp-fill-rdoc-comment)

Download