foca/tomdoc

Tomdoc.rb is a tool for Ruby programmers who want to generate clean, readable documentation from their code. It implements TomDoc, a documentation style that aims to make code comments understandable to humans without requiring any special formatting syntax. The idea is straightforward: when writing a method, you describe what it does in plain English, optionally list and explain its arguments, provide examples, and state what the method returns. This library parses those comments and turns them into formatted output. You can run it from the command line to print color-coded documentation in the terminal, or generate HTML pages for browsing in a web browser. You can also filter the output to find specific methods or classes by name. This would appeal to developers who want to keep their documentation close to the code but don't want to learn a complex markup language. A team lead could use it to generate a quick reference for a Ruby codebase, or an open-source maintainer could produce HTML docs to ship with their project. The TomDoc approach is appealing because the comments read naturally even before they are processed, you're just writing sentences above your methods. The project is notably lightweight in philosophy. The TomDoc format itself has only four simple steps, and the library focuses on doing one thing well: parsing that format and producing either terminal or HTML output. It was built and tested for Ruby 1.8.7, which is an older version of the language, so anyone using it today would want to verify compatibility with their setup. The README mentions a Ruby API for programmatic use, but notes that it is not yet fully documented, though, fittingly, you can use the tool to document itself by running it against its own source code.