Manual

Documentation coverage analysis for the PEAR packages documentation. Daily updated pear documentation stats can be found at pear.cweiske.de/coverage/.

Introduction

Introduction – What QA_Peardoc_Coverage is good for

About QA_Peardoc_Coverage

A great library is almost useless without documentation. PEAR has over 300 packages, automatically generated API documentation and a manual. The PEAR manual (the one you are reading) shall provide an overview on the packages and instructions about how to use them, and give an understanding about the classes in a package, and their methods. Further information about them can looked up in the API docs.

With the amount of packages PEAR provides, it's hard to keep track of the state of documentation of the packages - a tool to track this was needed. QA_Peardoc_Coverage is its incarnation.

QA_Peardoc_Coverage uses a SVN checkout of PEAR and PEARDOC to find out which packages are documented, which classes and method are mentioned in the docs, and which developers do a good job in documenting their code.

How it works

How it works – The global picture

How it works

The documentation analysis report generation is split into two processes:

Collect data and save it
Generate different reports from saved data

This was chosen because the data collection step takes a long time (~ 1 minute), but it's needed for every single report. So if you want to generate the simple doc coverage, and the extended one, you need the same base data - you just display it in a different way.

generateCoverage() in QA_Peardoc_Coverage generates and returns the array with the computed coverage data. It can be serialized and saved, since all the Renderer classes use it as input.

Classes implementing the QA_Peardoc_Coverage_Renderer interface provide a render() method that takes the data returned by generateCoverage() and return the analysis, most times a string containing HTML code.

Generating coverage analysis

Generating coverage analysis – Step by step

Generating coverage analysis data

Make sure you have a fresh checkout of pear and peardoc directories from cvs.php.net.
Configure peardoc to generate the manual.xml in there ( autoconf, ./configure).
Call genData.php with the path to peardoc's manual.xml as first, and path to the pear cvs directory as second parameter.
A file called doc.dat will be generated in the current working directory.

Generating HTML reports

Once the coverage data is generated and serialized, you can generate some HTML reports. For this, the packages provides four Renderer classes that all implement the QA_Peardoc_Coverage_Renderer interface:

QA_Peardoc_Coverage_Renderer_DeveloperList lists all developers with the number of packages they have, the number of undocumented packages and lists the undocumented ones. The list is sorted by percentage of documented packages.
QA_Peardoc_Coverage_Renderer_SimplePackageList lists all categories in PEAR, the packages in them and shows which of them have docs and which not. A final summary with the total number of existing and documented packages, and a percentage number is also given.
QA_Peardoc_Coverage_Renderer_ExtendetPackageList is similar to the simple list, but also shows the package's classes, their documentation state and their methods and their doc state. This list can be used to check which methods aren't yet covered by your documentation.
QA_Peardoc_Coverage_Renderer_MissingDocsPerDeveloper generates an array of developer email => array(package names) assignments that can be used as base data to send reminder emails.

All the renderers have a examples/gen*.php file that uses the doc.dat file written by examples/genData.php. They echo the html to the console, so you should redirect it into a file.