Documentation Guide (Doxygen)

General:

• SQL documentation is generated by on-the-fly translation of CREATE FUNCTION / CREATE AGGREGATE statements to C++ function declarations. This functionality is currently in beta status. Let me (Florian) know of bugs or feature requests.
• All module documentation should be moved to .sql_in files. See bayes.sql_in and regression.sql_in as examples.
• All uninstallation SQL files should end in "_drop.sql_in". Otherwise, they show up in doxygen as visual clutter in the file list.
• All files containing a "/sql/" in their path are excluded. These files are assumed to belong to regression tests and should not clutter the file list, either.
• I extended the SQL2C++ filter by this feature: Since PostgreSQL (the SQL standard?) disallows labeling the arguments of aggregate functions, the filter will automatically uncomment C-style comment that start with "/*+". Example:

CREATE AGGREGATE fancyAggregate(/*+ "identifierA" */ INTEGER) ( ... ) CREATE FUNCTION amazingFn(val DOUBLE PRECISION /*+ DEFAULT .01 */) RETURNS INTEGER ...

will be translated into:

<inferredReturnType> fancyAggregate(integer identifierA) { }; integer amazingFn(float8 val = .01) { };

• As always, to preserve capitalization use quotes ("iDeNtiFiEr"). Regression.sql_in has some aggregates that are documented this way.
• When in doubt, stick to the best practices of the language you are using. E.g., Python gives the following advice for its docstrings: http://www.python.org/dev/peps/pep-0257

Section Guide:

1. Create a new group for your module (in methods/mainpage.dox) and use @addtogroup your_module.
2. Write @about section to describe your algorithm.
3. Write @prereq section, for example: Requires SVEC MADlib module. Nothing about PostreSQL or Greenplum.
4. Write @usage section to describe the API. (In the future we may need to split this into os-level side and in-db side.
5. Write @examp section. The reason we say 'examp' (instead of example) is because we don't want to see this on a Doxygen example tab.
6. Use @literature to list your references.

See bayes.sql_in for good example.

Wish List:

• Support for all PostgreSQL types.
• Automatically document type definitions.

Recently implemented:

• Automatically document aggregate functions. The return type is inferred from the final function or, if missing, is the transition type.
• Line numbers are preserved.