C Source Code Documentation Assistant

Project Overview

srcdoc is a source code documentation tool that extracts function information from source code and formats man pages for the functions.

Basic information is obtained from the source code itself. The function name, parameters, and return type are always available. Comments preceding the function, as well as comments within the source code, are useful starting points for a function documentation page.

The main steps in documentation generation are:

1. Extract function information, including header files used, function syntax, and comments from the source code file.
2. Generate an intermediate file containing the function information in a pseudo-manpage format.
3. Open an editor (vi or gvim) and edit the extracted documentation to review and complete the documentation. This step can be omitted, generating the documentation directly from the source code.
4. Re-read the intermediate text file and generate a documentation page in either HTML or man format, or both.

Background

I've often obtained source code from somewhere that looks like it could be useful, but then end up spending a bunch of time in the source code trying to figure out how it works, and how to use the functions in the code. If I had a set of man pages, I figure, I would know how to call the function, what it would return, and maybe even some explanation. I can get that information, tediously, by searching the code.

The documentation tools that I've found typically expect special comments to specify the start and end of documentation, which is great if the developer wants to generate good documentation and has the self-discipline to write the documentation along with the code. I wanted to get documentation from the typical undisciplined coder.

SrcDoc uses a C parser to find functions and any comments associated with the functions. If the developer doesn't comment at all, at least the parser finds the functions, parameter types and names, and return types. That's a start, and being able to do 'man some_func' and get just that basic information is useful. Any description of those parameters and how the function works is even better. Often the developer will let slip some description that gives some clues, or from the starting point, I can add a description of functions that I use. So I can grow a set of pretty useful documentation for source code that didn't come with any.

Basics

SrcDoc uses a C source code parser and a document formatter. The parser was developed with Yacc (Bison) and executes on the C Pre-Processor output. It generates intermediate files which are read by the documentation formatter, which is all perl code.

More Details

The project User Guide proveds a more complete description of the project.

Downloads

Download the latest version of SrcDoc in [bzip2] or [gzip] format.