-
Notifications
You must be signed in to change notification settings - Fork 128
Documentation Guide (Doxygen)
- Latest release:
- User Doc http://doc.madlib.net/
- Developer Doc http://devdoc.madlib.net/
- Previous release (e.g: v0.1alpha):
- User Doc http://doc.madlib.net/v0.1alpha
- Developer Doc http://devdoc.madlib.net/v0.1alpha
- Main/Master branch:
- User Doc http://doc.madlib.net/master
- Developer Doc http://devdoc.madlib.net/master
- SQL documentation is supported by a Doxygen filter that translates CREATE FUNCTION / CREATE AGGREGATE statements to (empty) C++ function definitions. This functionality is currently in beta status. Let me (Florian) know of bugs or feature requests. If you are interested, the source code for the SQL2C++ filter consists of the flex and bison files sql.ll and sql.yy at https://github.com/madlib/madlib/tree/master/doc/src.
- Current features:
-
Translate CREATE FUNCTION and CREATE AGGREGATE statements into empty C++ function definitions
-
Both inline (C-style) comments of the form
/** ... */
and end-of-line comments of the form--! ...\n
are recognized as Doxygen comments -
Since PostgreSQL and GP disallow labeling the arguments of aggregate functions, the filter will automatically uncomment C-style comments that start with
/*+
(currently only at spots where it makes sense). The same can be used for default arguments (This is useful when using function overloading to mimic default arguments, which are not supported by Greenplum or PostgreSQL <= 8.2). ExampleCREATE 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) { };
-
For aggregates, the return type will be automatically inferred from the transition state / final function
-
Capitalization of identifiers will be preserved if put in quotes
"iDeNtiFiEr"
-
Line numbers are preserved
-
- Still to be implemented:
- Support for all PostgreSQL types
- Automatically generate documentation for type definitions
- 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.
- 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
- Create a new group for your module (in methods/mainpage.dox) and use
@addtogroup your_module
. - Write
@about
section to describe your algorithm. - Write
@prereq
section, for example:Requires SVEC MADlib module.
Nothing about PostreSQL or Greenplum. - Write
@usage
section to describe the API. (In the future we may need to split this into os-level side and in-db side. - 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. - Use
@literature
to list your references.
See bayes.sql_in for an example.