Documentation requirements
This document is a guide to technical documenting Microbizz. All Microbizz documentation in this wiki is performed in the mbdoc namespace and written in English.
Links to the actual pages should be listed at the end of this page.
How to document
Listed below are the requirements for different part of documentations.
Database tables
There must be a documentation page for every database table in Microbizz.
Each field in the database must be described according to type and content. For tables representing Record-objects a link to the page regarding the object should be linked instead.
Microbizz includes a script for generating wiki pages for all database table, see obj/Connect/php/dokuwiki_*.
Logic flows
A logic flow, is defined as a closed logic circuit in Microbizz. This could be the form system discussing how forms work in Microbizz, or internal registrations aiming on describing how the internal registration system works in Microbizz.
These descriptions should be technical in nature aimed at a programmer and provide a broad overview of the flow and the thoughts behind, and if possible a reference to further reading in the wiki.
Generic classes
A generic class is every PHP class defined in Microbizz.
Code documentation
All functions must be described with javadoc tagging and furthermore a javadoc header should be provided with an @author tag naming the person who knows most about this class or the goto-guy for questions regarding the class.
A number of @see tags of the form
@see <a href="http://wiki.microbizz.dk/PATH">SUBJECT</a>
must be provided linking to one or more relevant wiki pages. At least the following pages must be linked:
A page describing the class itself.
If the class is closely related to a database table - a link to the wikipage describing this table.
A link to at least one logic flow, where this class is relevant.
Wiki documentation
A wiki page must exists for every class.
The page should describe the purpose of the class and if there is a certain way to interact with, or use the class, this is described. For the class Report, a description on how a report is generated and which functions are used (and in what order) could be an example of things to describe. It isn't necessary to describe individual functions as this is done in the code.
Record classes
A class based on the Record-object or subsequent objects must be described as a generic class. Furthermore a field description is required on the page in the wiki, describing each Record2-field, its content and purpose.
Report classes
If a report is to be documented, it should be done on pages named Report <REPORTCODE>.
The purpose of the report must be documented and each field in the report should also be documented along with how it is calculated.
If a report is documented in the user documentation, this documentation can replace the technical documentation, as long as it live up to the same standards.
Code folders
A code folder is a specific folder in the /sys/ structure of the source code. A folder is only considered to be itself and not its subfolders. So /sys/todo/details/ is one folder and /sys/todo/details/qfs/ is another folder.
Code documentation
The code documentation requirements are the same as for the generic class. For the @see references, the following pages must be linked:
If the content of the folder is strongly related to one or more specific classes these should be linked.
A link to at least one logic flow, where the code residing in this folder is relevant.
Possible a link to a page describing the folder content. See below.
Wiki documentation
Many folders contains simple code. In this case it is valid to make a short description of the folder content in the javadoc header of the index.php file in the folder, and leave out a wiki page.
Helper functions
Helper functions are functions that are available in Microbizz either through general includes or by including certain scripts. These can be PHP functions or javascript functions. In PHP this term only covers functions which isn't members of a class, as these will have been described as pr. class above.
Simple functions can be documented inline in the code, for example datepicker.
More complex functions or function infrastructures is documented in the Wiki, and should be referred to directly from the function using the @see tag. These pages are also tagged mbdoc:function
Helper functions which isn't documented in the Wiki, should be present on this page helper functions along with a very short (1-2 line) abstract covering the functionality in order to gain an overview.
Patches
All patches must be documented on the patches page, which should include their modcode and their keyword, and a short description about how they work.
When applying a patch to a customer, it is also mandatory to describe this in the Microbizz CRM module under the customer.
When to document
Code documentation is mandatory. As this specification raises the bar for documentation, upgrades are made along daily work with the code, so if you work with something, you are also responsible for bringing the code documentation up to date.
Wiki documentation is recommended, but can be postponed, as long as we're talking about not-written-yet documentation. It is legal to link to wiki-pages which doesn't exists yet.
If documentation exists it is vital that this is valid, so it is not allowed to modify code so it contradicts the documentation without:
Rewriting the documentation.
Deleting the documentation in question.
The former is of course the preferred option.
A developer can request of another developer to document undocumented code within reason.
Style guide
Function names, variable names and field names should be styled like this: func(), $var, field.
Classes should be in italics, like Record2.
Filenames and paths should be styled like this: somefile.pdf.
Source code guidelines
Language guide
Common terms in the system is defined in the language guide; see also Side elementer.
External libraries
Microbizz uses a number of external libraries, and some of these have been modified to add Microbizz-specific funtionality, or perhaps Microbizz provides workarounds for bugs in the libraries. This may cause problems when upgrading the external libraries. Any changes/bugfixes/workarounds should be documented in details on the page below, so that they can be checked/reimplemented when/if the libraries are updated.