[[PageOutline(2-5,Contents,pullout)]]

= Add code tags (`XXX`, `FIXME`, `TODO`) to source code

== Description

Code tags are additions to the code or wiki pages that flag to the reader that attention is needed. 
 * `FIXME` is for things which are definitely broken, but where you want to not worry about it for the moment. Shows up as FIXME.
 * `TODO` is for useful features, optimizations or refactorings that might be worth doing in the future. Shows up as TODO. 
 * `XXX` is for things that require more thought and that are arguably broken.

See [http://c2.com/cgi/wiki?FixmeComment FixmeComment] for a background to this plugin.

You need a subdirectory named `cache` that is writeable by your Trac to make this work. This takes some time when it is first used. Also don't forget to grant the `CODETAGS_VIEW` permission to your users.

== Bugs

Existing bugs and feature requests for CodeTagsPlugin are 
[report:9?COMPONENT=CodeTagsPlugin here].

If you have any issues, create a 
[/newticket?component=CodeTagsPlugin new ticket].

[[TicketQuery(component=CodeTagsPlugin&group=type,format=progress)]]

== Feature Requests

* Feature "upgrade CodeTag to issue". Click on one of the CodeTags to be brought to a "New Ticket" page, with fields already completed (will require some parsing). Bonus points if the CodeTag (and surrounding comments, which might be numerous) can optionally be removed from the SVN and a commit log entry automatically generated.
* Having a huge code base makes the table with the tags so huge that even modern browsers can hardly display it. Maybe:
 * Split it up into multiple pages
 * Choose display for only specified tags
 * Chose display for only specified path in repository
* Allowing regex's for the [code-tags] fields would increase flexibility (scan_files, scan_folders, tags).

== Download / Source

The CodeTagsPlugin source can be found [https://github.com/trac-hacks/codetags here].

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

To enable this plugin, add the following to your `trac.ini` file:
{{{#!ini
[components]
codetags.* = enabled
}}}

== Configuration

Additional configuration options can be added to the `trac.ini` file:
{{{#!ini
[code-tags]
scan_files = *.html, *.py, *.c, *.h, *.hh, *.m, *.pch, *.hpp
scan_folders = trunk/*, branches/*
tags = XXX, TODO, FIXME, BUG
}}}

The following attributes can be defined:

 {{{scan_files}}} :: Specifies which file types to scan. Default: *, ie all files.

 {{{scan_folders}}} :: Specifies which directories within the repository to scan. Default: *, ie all files.

 {{{exclude_folders}}} :: Specifies directories that are subdirectories of {{{scan_folders}}} but don't need to be scanned.

 {{{exclude_files}}} :: Specifies files that shouldn't be scanned even though they're included by scan_files.

 {{{tags}}} :: Specifies what tags to locate, though only the defaults are colored at all. Default: XXX, TODO, FIXME.

By default, this plugin doesn't ignore binary files. If you use svn/trac in a web-dev environment, this is a pain, since the tagger finds tags in files such as `.gif`. This, however, shouldn't be a serious problem, because CodeTagsPlugin searches for word boundaries (regex '\b') at the edges of words.