D'Note

This is a fork of Rubyworks' D'Note.

Developer's take note! All those TODO's and FIXME's floating around your source code are rotting away. They are trapped, and in desperate need of your attention.

But not to fret! D'Note will help you liberate them. D'Note will scan your source code for labeled comments; collect, collate and sort them; and then return them to you in a format of your choosing. Wunderbar!

Note Structure

D'Note scans for the common "LABEL:" pattern (all-caps label followed by a colon) used by many developers of many languages. To be more specific, for D'Note to recognize a note, it needs to conform to the following simple set of rules:

1) Notes start with an all-caps label punctuated with a colon, followed by the note's text.

  # LABEL: description ...
  

2) Any note that requires more than one line must remain flush to the left margin (the margin is set by the first line). This is done because RDoc will mistake the second line for a <pre> block if it is indented.

  # LABEL: description ...
  # continue ...
  

3) An alternative to the limitation of the last rule is to indent the whole note (making the whole note a <pre> block with regards to RDoc). Then the text layout is free-form.

  # This is a description of something...
  #
  #   LABEL: description ...
  #          continue ...
  

That's all there is to it. If I can convince the developers of RDoc to add recognition of labels, we may eventually be able to relax the flush rule too, which would be very nice.

There is also a command-line option, --no-colon, which deactives the need for a colon after the note label. However this often produces false positives, so it's use is discouraged.

Generating Notes

As you can see the commandline interface is quite straight-forward.

  USAGE:

    dnote [OPTIONS] path1 [path2 ...]
   
  OUTPUT FORMAT: (choose one)
      -f, --format NAME                select a format [text]
      -C, --custom FILE                use a custom ERB template
          --file                       shortcut for text/file format
          --list                       shortcut for text/list format

  OTHER OPTIONS:
      -l, --label LABEL                labels to collect
          --[no-]colon                 match labels with/without colon suffix
      -m, --marker MARK                alternative remark marker
      -u, --url TEMPLATE               url template for line entries (for HTML)
      -c, --context INTEGER            number of lines of context to display
      -x, --exclude PATH               exclude file or directory
      -i, --ignore NAME                ignore file based on any part of pathname
      -t, --title TITLE                title to use in header
      -o, --output PATH                save to file or directory
      -n, --dryrun                     do not actually write to disk
          --debug                      debug mode
   
  COMMAND OPTIONS:
      -T, --templates                  list available format templates
      -h, --help                       show this help information
  

There are a variety of formats are available, here are examples of some of the XML, HTML and YAML formats. You can get a list of all available format templates using the -T option.

The default path is **/*.rb and the default format -f text. Here is an example of DNote's own notes in -f rdoc format:

  = Development Notes

  == TODO

  === file://lib/dnote/notes.rb

  * TODO: Add ability to read header notes. They often
  have a outline format, rather then the single line. (19)
  * TODO: Need CSS? (22)
  * TODO: Need XSL? (24)

  === file://plug/syckle/services/dnote.rb

  * TODO: Should this service be part of the +site+ cycle? (18)

  (4 TODOs)
  

In the future the parsing may imnprove to allow page-top outlined notes as well.