Introducing PXR: A Cross-Referencing Documentation Compiler : Windows Research Kernel @ HPI

By Alexander Schmidt

Quite some time ago, Michael posted an article about our filter for the Doxygen documentation compiler. While Doxygen is a great tool for documenting large source code repositories, we had some issues with the results that were generated. For example, we had several cases, where Doxygen linked to the prototype declaration of a function instead of its definition. We also wanted a Web site that leverages Web 2.0 capabilities such as AJAX to further enhance the user experience, which is why we decided to build our own documentation compiler: PXR. In this article, we want to briefly introduce PXR and to give you an impression of what it looks like:

PXR was designed as a middle- and back-end for the Microsoft C compiler by means of the Microsoft Phoenix compiler framework. That means, the compiler parses the source files and builds up its intermediate (internal) representation (IR) of the code. PXR then analyzes this IR to generate HTML output. In addition to the comiler information, we also leverage pre-processor output to analyze macros and their value at compile time.

One goal of PXR is to make access to certain aspects of the WRK sources as simple as possible, which is why PXR groups the resulting output into three categories: functions, types, and macros. We intentionally abstract from the file and module hierarchy, because when you start working with the WRK you start picking some functions and data structures first to continue digging into the internals. A fourth category, the typedef alias category, was added later for the sake of completeness. For each category, a list of items is shown in the navigation bar on the left side of the page shown above. The filter input allows a user to search for phrases in each of the categories. Besides of that, following is a list of features PXR provides.

Functions

For each function, PXR shows the following information section: the function signature, a description, a simplified call graph, callers, references, and the source code itself. Each section can be collapsed or expanded. In the following figure, only the signature, call graph, and source code section are open.

The "Doc String" section contains a description of what the function is doing, what its parameters mean, and how the return value is to be interpreted. This information is directly parsed from the sources as the WRK follows a pretty strict annotation scheme. To give you an idea of the doc string, please see the following figure:

Data Type Dialogs

Whenever source code is shown on a PXR rendered page, it is both highlighted and hyperlinked. That means, if PXR is aware of further information for a particular identifier in the source code, it will embedd a link to the respective further information. For data types, we decided not to open another tab on the PXR screen, but rather to open a "window", so as to not distract you from reading the source code of a function. However, if you want to follow a link to another function, PXR will open a new tab for this function as this item contains too much information to be reasonably presented in a window.

Source Code Folding

PXR allows you to fold away unnecessary code blocks, such as if and else blocks. This is to make reading and understanding the flow through the code more easily, as you can concentrate on particular code paths while making invisible those paths that are of minor interest. In the following figure, the if block on lines 4832 thru 4869 was folded away. It can be made visible again by clicking the "+" icon.

Interested in PXR?

We made our version of the WRK sources available online to faculty members at www.dcl.hpi.uni-potsdam.de/wrk-pxr/. If you want to have a look yourself and you are a faculty member, please contact compsci@microsoft.com and we will be happy to create an account for you. We further plan to publish our HTML version of the source code at Faculty Connection at the beginning of next month. The PXR tool itself is currently not available but we are working on that. Please feel free to leave us any comments or requests for features.

Comments