libclc documentation policy Content: 1) History 2) Introduction 3) Scope 4) Rationale 5) Documentation format 6) Example 1) History ------- Contributors: Bertrand Mollinier Toublet - bertrand.molliniertoublet@enst-bretagne.fr Randy Howard - randy.howard@FOOmegapathdslBAR.net 03/14/03 - bmt - Initial draft 2) Introduction [bmt] ------------ This document discusses and describes documentation guidelines for the libclc project, an ISO C implementation of an ad-hoc extension library, hosted at http://libclc.sourceforge.net. Note: this document is currently a draft. Comments are welcome either on comp.lang.c, directly to the authors listed above or on the libclc mailing list at libclc-developers@lists.sourceforge.net. 3) Scope [bmt] ----- Ideally, this document should be required reading for every implementor participating in the libclc project. They should follow the guidelines described here and submit the required documents with their contribution. 4) Rationale [bmt] --------- Following encapsulation principles, in all libclc modules, the emphasis should be on interface and documented functionality. In this spirit, the code is only to be considered as the means to achieve functionality. Thus, libclc documentation, while remaining clear and user-friendly shall be the first document produced in the design of a module, and it should describe the module's interface, valid inputs, expected outputs, error cases and handling. Within the code itself, there is no need to document what could be considered as user information. On the other hand, for the sake of maintenance, specific unclear bits of code, unusual algorithms and the like should be adequately documented in a free format. As a consequence, autodoc tools, such as Doxygen are not adapted to our needs, as they have the code-documentation dependency wrong: if the user documentation lies in the code, it is only too easy for a maintainer to slip and adapt the documentation to its current maintenance task. Given these premises, it appears as a good idea, if not a necessity to produce documentation in a powerful, dynamic, self-documenting format. For example, documentation could be produced in HTML format, with embedded cross-references, indexes and other useful navigation tools. A (very brief) tour of the state-of-the-art in documentation shows that DocBook is a pretty powerful format that serves the purpose of allowing the production of good quality documentation while keeping the maintenance cost low. Then again, it would be very presomptuous to expect from all the contributors to libclc to master DocBook (which is no more than an SGML format), or XML or even HTML for that matter. We are thus faced with solving the apparent dilemma of producing quality documentation source while keeping the burden to the contributor to a minimum. I think that adequate templates would help solve this dilemma. The contributors would be thus only expected to fill in the gaps in a nicely prepared template. Since the documentation manager, like everyone else, is in a learning process, none of these templates are currently available (mainly because the documentation manager has to learn DocBook first ;-). As a transitional solution, contributors shall produce a simply formatted text-based documentation, mimicking the man page format, as described below. In the meantime, the documentation manager will work on producing adequate templates, and as soon as those are ready, the contributors will switch to produce documentation in the new format. 5) Documentation format [bmt with examples from rh] -------------------- The proposed format is a mimick of the manpage format: a module documentation shall be made of a set of text documents each describing a given function. Each document shall be divided in the following sections: 5.1) SYNOPSIS This section shall indicate in three groupings what are the required include files, the function prototype, and the required library to link against. Example: SYNOPSIS #include "clc.h" char *clc_strdup(const char *s); Link with: libclc 5.2) DESCRIPTION This section shall provide a detailed description for the function, including behaviour, valid input range and expected outputs, as well as any comments relevant to usage of the function. Example: DESCRIPTION clc_strdup() - returns a pointer to a newly allocated string which is an exact duplicate of the string s. Memory for the resulting new string is allocated with malloc() and should be freed with free(). 5.3) PARAMETERS This section shall describe the parameters that the function accepts, as well as their range of validity, and any relevant additional comment. Example: PARAMETERS s - This is the string terminated with a '\0' character to be duplicated. 5.4) RETURN VALUE This section shall describe the return value to expect from the function, as well as any additional relevant comment. Example: RETURN VALUE Upon successful completion clc_strdup() returns a pointer to a copy of s. Otherwise NULL is returned and errno is set to indicate the error. 5.5) EXAMPLES This section shall indicate one or more meaningful example of usage of the function as an illustration for the documentation reader. Example: EXAMPLES char *s = "This is a test"; char *s2 = NULL; s2 = strdup(s); if (s2) { printf("%s\n", s2); } 5.6) ERRORS This section shall indicates what values errno can be set to in case an error occurs in the function. For each error, an adequate description of the error conditions shall be given. Example: ERRORS CLC_ENOMEM clc_strdup() was not able to allocate a sufficient storage for the duplicate of s. 5.7) BUGS This section shall indicate existing known bugs in the implementation of the function, as well as possible workaround and pointers to updates/patches. Example: BUGS None reported. 5.8) SEE ALSO This section shall indicate a list of resource and cross-references of interest for the reader in the context of this function. Example: SEE ALSO clc(clc) 6) Example [rh] ------- Thus, a full document for the hypothetical function clc_strdup would look like this: clc_strdup(clc) SYNOPSIS #include char *clc_strdup(const char * CLC_RESTRICT s); Link with: libclc DESCRIPTION clc_strdup() - returns a pointer to a newly allocated string which is an exact duplicate of the string s. Memory for the resulting new string is allocated with malloc() and should be freed with free(). PARAMETERS s - This is the string terminated with a '\0' character to be duplicated. RETURN VALUE Upon successful completion clc_strdup() returns a pointer to a copy of s. Otherwise NULL is returned and to indicate the error. EXAMPLES char *s = "This is a test"; char *s2 = NULL; s2 = strdup(s); if (s2) { printf("%s\n", s2); } ERRORS CLC_ENOMEM clc_strdup() was not able to allocate a sufficient storage for the duplicate of s. BUGS None reported. SEE ALSO clc(clc)