Doxygen series introduction

One of the bigger projects I've undertaken this year, then, has been one to clean up our documentation and the methods we have of accessing it. Our existing manual system has a number of issues:

  1. The people who developed the initial documentation and updates along the way are, by and large, no longer active developers for the MUD.
  2. Much of the documentation, which has been kept separate from the code, is out of date.
  3. The documentation system is coded in such a way that a document in one section may preclude the presentation of documents from another section.
  4. The documentation system can be cumbersome to navigate
  5. Many functions are undocumented, leaving the manual system unaware of their existence
  6. Because no documents know about each other and the system relies on directory structure, work is often duplicated.
  7. Sometimes the nomenclature of the directories is misunderstood and incorrect documents are included, which further promotes further misuse of the system.

Finding a Solution

Our primary administrator attempted to approach the issue in 2010 by installing Doxygen and running it over a majority of the mudlib in what would eventually become a big step forward. The doxygen system's primary initial advantage was that we could use the index of file members to look up functions. In many cases functionality was provided in what we'll call a mudlib_applied function call, which I intend to be the mudlib analogue to the "driver applied" concept traditionally discussed in /doc/driver/applied/ and /doc/driver/applied/applied--but the catch was that code leaning on these calls is rarely documented and one must look to other objects which implement those applied functions to decipher their usage. (It is now considered best practice to define such functions in the blueprints you intend to call them, and document their usage, allowing Doxygen to index them.) Doxygen made tracking these uses down a bit easier in a large code base, but the initial benefits were restricted to this, due to the limitations of a stock install:

  1. Doxygen natively understands C, but not all LPC idioms. At a glance, it looks like Doxygen has understood the mudlib code (I've in fact spoken to other mud admins using doxygen to document mudlibs who hadn't yet even noticed the gaps in how doxygen was handling the code. Doxygen doesn't natively understand LPC inheritance, and it can't decipher #inherit MACRO_NAME statements which reference global macros.
  2. Doxygen doesn't understand our LPC files as classes, which is more or less how they're treated by the driver.
  3. Default LPC function visibility is public, while Doxygen will interpret many of our functions differently based on the languages we have it set to interpret it; functions not given explicit visibility may get identified as private.

It's probably worth noting here in the introduction that our Doxygen implementation/configuration and standards are still evolving as we make tweaks to suit our needs.

Discussing this elsewhere?
Enter 'link' for a markdown link
or 'tweet <message>' for a pre-populated Tweet :)
Want to subscribe? Enter 'rss' for a feed URL.
>