Good API needs good Reference
Documents section was just a link to Doxygen output. Although the code is extensively documented, doxygen output was an unmanaged blob in the site. It was impossible to create unified links to the documentation as doxygen created random hashes for each class or member.
However in-code documentation is better than separate documents as it follows same revisioning and documenting is streamlined along with developing. At the same time doxygen is a great parser with a very rich command set. Based on those two facts, a new "API Reference" section was build to overcome previous problems but still using doxygen comments.
The concept is simple, we use doxygen to parse code and create an XML with the documentation. Inside the administrative panel of the site there is a parser for doxygen XML files, where the administrator can upload the XML output for each release. The site parses XML file and populate the database with doxygen documentation in a relational structure. A new frontend was build to browse documentation easily with unified urls. For example http://phplibs.kmfa.net/api/Grid/__construct will show documentation for member __construct() of class Grid.
Although currently this is not visible to the end user. New "API Reference" carries another big change, documentation is saved per release, permitting multiple version of documentation to be viewable from the frontend.
Along with this big update, there are some other changes. News system has finally RSS feeds and it also supports basic newsletter functionality.
However in-code documentation is better than separate documents as it follows same revisioning and documenting is streamlined along with developing. At the same time doxygen is a great parser with a very rich command set. Based on those two facts, a new "API Reference" section was build to overcome previous problems but still using doxygen comments.
The concept is simple, we use doxygen to parse code and create an XML with the documentation. Inside the administrative panel of the site there is a parser for doxygen XML files, where the administrator can upload the XML output for each release. The site parses XML file and populate the database with doxygen documentation in a relational structure. A new frontend was build to browse documentation easily with unified urls. For example http://phplibs.kmfa.net/api/Grid/__construct will show documentation for member __construct() of class Grid.
Although currently this is not visible to the end user. New "API Reference" carries another big change, documentation is saved per release, permitting multiple version of documentation to be viewable from the frontend.
Along with this big update, there are some other changes. News system has finally RSS feeds and it also supports basic newsletter functionality.
Posted 20/11/2009 from sque
RSS Feed