source: trunk/doc/developers.txt @ 162

/**
 * @mainpage Instructions for the developers of Libpspio
 *
 * @section Introduction
 * 
 * One important aspect to pay attention to is to always distinguish clearly
 * the difference between what a developer of the library needs and what a
 * user of the library developing some other code will have to access. This
 * is not always easy to achieve, because of the confusion generated by the
 * users of the library being actually developers themselves. The related
 * concepts are explained practically in the following sections.
 * 
 * 
 * @section C headers
 * 
 * All headers containing data that will be accessed by the users of the
 * library should be clearly identified and preserved from name clashes.
 * They are thus always prefixed by "pspio_". They also have to include the
 * minimum amount of data possible, i.e. the C headers required by the
 * exported routines (e.g. stdio.h) are included in the C files only. These
 * "pspio_*.h" headers are listed in the makefile in the "pio_core_hdrs"
 * variable.
 *
 * Headers which are strictly internal to Libpspio do not have a priori to
 * follow strict naming conventions, but it is always a good idea to name
 * them cleverly, so that their purpose is known from reading their name.
 * These headers are listed in the makefile in the "pio_hidden_hdrs"
 * variable.
 *
 * The headers belonging to Libpspio are included using double quotes,
 * while those coming from other libraries are included using the <toto.h>
 * convention. The config.h file is included in the C files only and is
 * always the last to be included, as it may fine-tune some already-defined
 * parameters and work around some issues. One noticeable exception is
 * the conditional including of headers, which should of course be
 * placed after including config.h.
 *
 *
 * @section Private extensions of external libraries
 *
 * Extending privately the capabilities of an external library is not a good
 * idea on the long run, since its developers may decide at some point to
 * extend the capabilities in an incompatible way. Always prefer to discuss
 * of such extensions directly with them. You might get them earlier than
 * you expect.
 */