Annotations

Extracts and displays annotations from source code comments like these:

class MyModel
  def find(id)
    # TODO: Find the thing
  end
end

The output looks like this:

./lib/my_model.rb:
  * [ 17] [TODO] Find the thing

Annotations is a standalone library derived from the notes tasks in Rails 3.2.1, extracted into its own gem so it can be used in non-Rails (or even non-Ruby) projects.

Annotations looks for TODO, FIXME, and OPTIMIZE comments in the following kinds of source code files:

Syntax	Supported file extensions
Ruby	.rb, .builder, Gemfile, Rakefile
ERb	.erb, .rhtml
CoffeeScript	.coffee
Sass	.scss, .sass
PHP	.php

Installation

Add this line to your application's Gemfile:

gem 'annotations'

Or install it yourself as:

$ gem install annotations

Usage

Add the Annotations tasks to your Rakefile:

require 'annotations/rake_task'

Annotations::RakeTask.new

This will add the following tasks:

$ bundle exec rake -T notes
rake notes                     # Enumerate all annotations
rake notes:custom[annotation]  # Enumerate a custom annotation
rake notes:fixme               # Enumerate all FIXME annotations
rake notes:optimize            # Enumerate all OPTIMIZE annotations
rake notes:todo                # Enumerate all TODO annotations

If you want to name the tasks something other than "notes", just pass the name you want to use into RakeTask.new:

Annotations::RakeTask.new(:devnotes)

You can also set the default tag list when defining the task, using this block syntax:

Annotations::RakeTask.new do |t|
  # This will add an additional 'WTF' annotation; it will be included in
  # `rake notes`, and a `rake notes:wtf` task will be added
  t.tags = [:fixme, :optimize, :todo, :wtf]
end

Once your Rakefile is set up, run the tasks to view your notes:

rake notes

Runtime options

Filter by file extension: Only display annotations for certain kinds of files. (Thanks for Gabriel Schammah for contributing this feature.)

rake notes:todo ext=js,rb,coffee

Roadmap

• Ability to set/limit the search path(s) for annotations (currently set to '.')
• Color output
• Standalone command-line tool (e.g. annotations wtf todo --color)
• More robust handling of different extensions/comment formats, plus the ability to easily add in new ones
• Test coverage!!

Contributing

Fork the project, make some changes on a feature branch, then send a pull request.