Basic configuration

This post discusses the basic configuration options we've used to configure Doxygen to cope with LPC, while some later posts in this series will also deal with some more advanced topics along these lines. The first section of this post discusses the options which have bearing on making the documentation useful for LPC--other options which are a matter of taste go undiscussed--and the second section includes a copy of our current configuration. I also recommend you locally install doxygen (I use doxywizard, since I'm using windows) so you can experiment without re-running doxygen on your MUD's server. We have webdav set up, so I'm able to run doxygen with a local config on a very small subset of the guides/mudlib to test changes to them in about 30 seconds instead of the 50 minutes or so our full doxygen run takes.


Important Options

In order of their appearance within the configuration file:

  • OUTPUT_DIRECTORY: This is more of a note/warning than a real important option--when Doxygen starts running for a given output type, it wipes the current output directory for that type (so given our example, /usr/users/lib/www/wizards/secure/doxygen/html/ is scrubbed). If you need documentation to be accessible while Doxygen is running (more important the larger your codebase is) you may want to output to one directory, and have a script then copy/archive the output directory over to a new location where the files are actually served from.
  • INLINE_INHERITED_MEMB: While strictly speaking this isn't necessary, many of the builders our documentation needs to serve aren't particularly well-versed in the concept of inheritance; showing all available members within the class documentation helps them better understand the object's functionality.
  • JAVADOC_AUTOBRIEF: Our documentation standards prioritize clean, plain-language prose function documentation--this setting interprets the first sentence of this description as the "brief" and encourages quality prose comments. This setting also helps make comments within the code more legible.
  • INHERIT_DOCS: Along with INLINE_INHERITED_MEMB, this helps make class documentation more comprehensive.
  • ALIASES: We use these aliases to help us replicate the unix/man doc style in which most of the driver/efun documentation comes. The synopsis section in particular is noteworthy; doxygen extracts a function definition for us, but the traditional practice of providing a prototype for all possible returns and argument combinations needs additional support. While greater discussions of our documentation style and the process of generating these documents will follow (and include examples) in subsequent parts of this series.
  • EXTENSION_MAPPING: My explanation of this should be taken with a grain of salt as I know neither C, C++ nor Java--but we've ultimately settled on mapping our C files to use doxygen's java interpreter. It seems like this best reflects how we define scope/visibility in LPC while doxygen seems to be capable of falling back into other modes to recognize non-java concepts which LPC does support. If someone else finds a better language to map to, however--let us know and I'll update this section.
  • MARKDOWN_SUPPORT: Markdown support allows us to have more plain-language-friendly documentation (Although we will note that we've suffered some consternation over issues with bugs in doxygen's markdown implementation causing changes/breaks between doxygen builds.
  • EXTRACT_ALL: Even if all of our members aren't documented, we like the verification having all members included provides, and the meta-data/graph generation for even undoc'd members.
  • INPUT/RECURSIVE: To restrict what was getting parsed and cut down on the run time, we switched from a recursive run on two root directories containing mudlib objects to include explicit directories; we add to the list as we find ourselves looking for documentation that isn't generated.
  • EXCLUDE_PATTERNS: It's common for an old MUD to have backup dirs/files sitting around--so we want to make sure we aren't accidentally including files that aren't live.
  • FILTER_PATTERNS: This is where much of the magic takes place; the LPC filter is written in python and corrects our source code to help doxygen understand our inheritance method and the fact that each file should be considered a class/object (more on this in part 3). You'll note that there's an early pattern for catching files in our current example directory. In theory we are supposed to be able to use FILTER_SOURCE_PATTERNS to create this exception--but in practice we weren't able to get it working. In the future it may be possible to do this properly. For now we direct the example files to an empty filter, and all other .c files to our LPC filter.
  • FILTER_SOURCE_FILES: We didn't really want to have to enable this option as it makes what we see in Doxygen a bit different than what the game runs on, however, it's necessary for the source browser to find our function definitions as the input filter throws off our line counts a little.
  • PREDEFINED: Our predefined setting is empty in our default config--we have a server-side cron operation that writes items from out from our global include file into the predefined category and generates the production-ready conf file. More on this in part 6.

Current Config

  1# Doxyfile  1.8.2
  2#---------------------------------------------------------------------------
  3# Project related configuration options
  4#---------------------------------------------------------------------------
  5DOXYFILE_ENCODING      = UTF-8
  6PROJECT_NAME           = Tsunami
  7PROJECT_NUMBER         =
  8PROJECT_BRIEF          =
  9PROJECT_LOGO           =
 10OUTPUT_DIRECTORY       = /usr/users/lib/www/wizards/secure/doxygen
 11CREATE_SUBDIRS         = YES
 12OUTPUT_LANGUAGE        = English
 13BRIEF_MEMBER_DESC      = YES
 14REPEAT_BRIEF           = YES
 15ABBREVIATE_BRIEF       =
 16ALWAYS_DETAILED_SEC    = NO
 17INLINE_INHERITED_MEMB  = YES
 18FULL_PATH_NAMES        = YES
 19STRIP_FROM_PATH        = /usr/users/lib
 20STRIP_FROM_INC_PATH    = /usr/users/lib
 21SHORT_NAMES            = NO
 22JAVADOC_AUTOBRIEF      = YES
 23QT_AUTOBRIEF           = NO
 24MULTILINE_CPP_IS_BRIEF = NO
 25INHERIT_DOCS           = YES
 26SEPARATE_MEMBER_PAGES  = NO
 27TAB_SIZE               = 8
 28ALIASES                = "usage{1}=@par Usage:\n@code\n\1@endcode" \
 29                         "synopsis{1}=@par Synopsis:\n@code\n\1@endcode" \
 30                         "history{1}=@par History:\n@code\n\1@endcode"
 31TCL_SUBST              =
 32OPTIMIZE_OUTPUT_FOR_C  = NO
 33OPTIMIZE_OUTPUT_JAVA   = NO
 34OPTIMIZE_FOR_FORTRAN   = NO
 35OPTIMIZE_OUTPUT_VHDL   = NO
 36EXTENSION_MAPPING      = c=java
 37MARKDOWN_SUPPORT       = YES
 38    AUTOLINK_SUPPORT       = YES
 39BUILTIN_STL_SUPPORT    = NO
 40CPP_CLI_SUPPORT        = NO
 41SIP_SUPPORT            = NO
 42IDL_PROPERTY_SUPPORT   = NO
 43DISTRIBUTE_GROUP_DOC   = NO
 44SUBGROUPING            = YES
 45INLINE_GROUPED_CLASSES = NO
 46INLINE_SIMPLE_STRUCTS  = NO
 47TYPEDEF_HIDES_STRUCT   = NO
 48SYMBOL_CACHE_SIZE      = 0
 49LOOKUP_CACHE_SIZE      = 0
 50
 51#---------------------------------------------------------------------------
 52# Build related configuration options
 53#---------------------------------------------------------------------------
 54EXTRACT_ALL            = YES
 55EXTRACT_PRIVATE        = YES
 56EXTRACT_PACKAGE        = YES
 57EXTRACT_STATIC         = YES
 58EXTRACT_LOCAL_CLASSES  = YES
 59EXTRACT_LOCAL_METHODS  = YES
 60EXTRACT_ANON_NSPACES   = YES
 61HIDE_UNDOC_MEMBERS     = NO
 62HIDE_UNDOC_CLASSES     = NO
 63HIDE_FRIEND_COMPOUNDS  = NO
 64HIDE_IN_BODY_DOCS      = YES
 65INTERNAL_DOCS          = NO
 66CASE_SENSE_NAMES       = YES
 67HIDE_SCOPE_NAMES       = YES
 68SHOW_INCLUDE_FILES     = YES
 69FORCE_LOCAL_INCLUDES   = NO
 70INLINE_INFO            = YES
 71SORT_MEMBER_DOCS       = YES
 72SORT_BRIEF_DOCS        = YES
 73SORT_MEMBERS_CTORS_1ST = NO
 74SORT_GROUP_NAMES       = YES
 75SORT_BY_SCOPE_NAME     = NO
 76STRICT_PROTO_MATCHING  = NO
 77GENERATE_TODOLIST      = YES
 78GENERATE_TESTLIST      = YES
 79GENERATE_BUGLIST       = YES
 80GENERATE_DEPRECATEDLIST= YES
 81ENABLED_SECTIONS       =
 82MAX_INITIALIZER_LINES  = 35
 83SHOW_USED_FILES        = YES
 84SHOW_FILES             = NO
 85SHOW_NAMESPACES        = YES
 86FILE_VERSION_FILTER    =
 87LAYOUT_FILE            = /usr/users/lib/etc/DoxygenLayout.xml
 88CITE_BIB_FILES         =
 89
 90#---------------------------------------------------------------------------
 91# configuration options related to warning and progress messages
 92#---------------------------------------------------------------------------
 93QUIET                  = YES
 94WARNINGS               = YES
 95WARN_IF_UNDOCUMENTED   = YES
 96WARN_IF_DOC_ERROR      = YES
 97WARN_NO_PARAMDOC       = NO
 98WARN_FORMAT            = "$file:$line: $text"
 99WARN_LOGFILE           = doxylog
100
101#---------------------------------------------------------------------------
102# configuration options related to the input files
103#---------------------------------------------------------------------------
104INPUT                  = /usr/users/lib/std/ \
105                         /usr/users/lib/obj/ \
106                         /usr/users/lib/obj/daemons/ \
107                         /usr/users/lib/obj/doxy_guide/ \
108                         /usr/users/lib/obj/handlers/ \
109                         /usr/users/lib/obj/shadows/ \
110                         /usr/users/lib/obj/room/ \
111                         /usr/users/lib/obj/living/ \
112                         /usr/users/lib/obj/monster/ \
113                         /usr/users/lib/obj/messaging/ \
114                         /usr/users/lib/obj/messaging/grammar/ \
115                         /usr/users/lib/obj/master/ \
116                         /usr/users/lib/obj/player/ \
117                         /usr/users/lib/obj/simul_efun_new/approved/ \
118                         /usr/users/lib/obj/register/ \
119                         /usr/users/lib/std/data_structures/ \
120                         /usr/users/lib/std/maze/ \
121                         /usr/users/lib/std/equipment/ \
122                         /usr/users/lib/std/monster/ \
123                         /usr/users/lib/std/object/
124INPUT_ENCODING         = UTF-8
125FILE_PATTERNS          = *.c \
126                         *.cc \
127                         *.cxx \
128                         *.cpp \
129                         *.c++ \
130                         *.d \
131                         *.java \
132                         *.ii \
133                         *.ixx \
134                         *.ipp \
135                         *.i++ \
136                         *.inl \
137                         *.h \
138                         *.hh \
139                         *.hxx \
140                         *.hpp \
141                         *.h++ \
142                         *.idl \
143                         *.odl \
144                         *.cs \
145                         *.php \
146                         *.php3 \
147                         *.inc \
148                         *.m \
149                         *.mm \
150                         *.dox \
151                         *.py \
152                         *.f90 \
153                         *.f \
154                         *.for \
155                         *.vhd \
156                         *.md \
157                         *.markdown \
158                         *.vhdl
159RECURSIVE              = NO
160EXCLUDE                =
161EXCLUDE_SYMLINKS       = NO
162EXCLUDE_PATTERNS       = *test* \
163                         *.bak \
164                         *-bak.c \
165                         */bak/* \
166                         */old/* \
167                         *archive*
168EXCLUDE_SYMBOLS        =
169EXAMPLE_PATH           = /usr/users/lib/players/misery/doxyexamp/
170EXAMPLE_PATTERNS       =
171EXAMPLE_RECURSIVE      = YES
172IMAGE_PATH             =
173INPUT_FILTER           = /usr/users/bin/lpc.py
174FILTER_PATTERNS        =
175FILTER_SOURCE_FILES    = YES
176FILTER_SOURCE_PATTERNS = *.example=
177
178#---------------------------------------------------------------------------
179# configuration options related to source browsing
180#---------------------------------------------------------------------------
181SOURCE_BROWSER         = YES
182INLINE_SOURCES         = YES
183STRIP_CODE_COMMENTS    = NO
184REFERENCED_BY_RELATION = YES
185REFERENCES_RELATION    = YES
186REFERENCES_LINK_SOURCE = YES
187USE_HTAGS              = NO
188VERBATIM_HEADERS       = YES
189
190#---------------------------------------------------------------------------
191# configuration options related to the alphabetical class index
192#---------------------------------------------------------------------------
193ALPHABETICAL_INDEX     = YES
194COLS_IN_ALPHA_INDEX    = 5
195IGNORE_PREFIX          =
196
197#---------------------------------------------------------------------------
198# configuration options related to the HTML output
199#---------------------------------------------------------------------------
200GENERATE_HTML          = YES
201HTML_OUTPUT            = html
202HTML_FILE_EXTENSION    = .html
203HTML_HEADER            =
204HTML_FOOTER            =
205HTML_STYLESHEET        =
206HTML_EXTRA_STYLESHEET  =
207HTML_EXTRA_FILES       =
208HTML_COLORSTYLE_HUE    = 220
209HTML_COLORSTYLE_SAT    = 100
210HTML_COLORSTYLE_GAMMA  = 80
211HTML_TIMESTAMP         = YES
212HTML_DYNAMIC_SECTIONS  = YES
213HTML_INDEX_NUM_ENTRIES = 100
214GENERATE_DOCSET        = NO
215DOCSET_FEEDNAME        = "Doxygen generated docs"
216DOCSET_BUNDLE_ID       = org.doxygen.Project
217DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
218DOCSET_PUBLISHER_NAME  = Publisher
219GENERATE_HTMLHELP      = NO
220CHM_FILE               =
221HHC_LOCATION           =
222GENERATE_CHI           = NO
223CHM_INDEX_ENCODING     =
224BINARY_TOC             = NO
225TOC_EXPAND             = NO
226GENERATE_QHP           = NO
227QCH_FILE               =
228QHP_NAMESPACE          = org.doxygen.Project
229QHP_VIRTUAL_FOLDER     = doc
230QHP_CUST_FILTER_NAME   =
231QHP_CUST_FILTER_ATTRS  =
232QHP_SECT_FILTER_ATTRS  =
233QHG_LOCATION           =
234GENERATE_ECLIPSEHELP   = NO
235ECLIPSE_DOC_ID         = org.doxygen.Tsunami
236DISABLE_INDEX          = NO
237GENERATE_TREEVIEW      = YES
238ENUM_VALUES_PER_LINE   = 4
239TREEVIEW_WIDTH         = 250
240EXT_LINKS_IN_WINDOW    = NO
241FORMULA_FONTSIZE       = 10
242FORMULA_TRANSPARENT    = YES
243USE_MATHJAX            = NO
244MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
245MATHJAX_EXTENSIONS     =
246SEARCHENGINE           = YES
247SERVER_BASED_SEARCH    = NO
248
249#---------------------------------------------------------------------------
250# configuration options related to the LaTeX output
251#---------------------------------------------------------------------------
252GENERATE_LATEX         = NO
253LATEX_OUTPUT           = latex
254LATEX_CMD_NAME         = latex
255MAKEINDEX_CMD_NAME     = makeindex
256COMPACT_LATEX          = NO
257PAPER_TYPE             = a4
258EXTRA_PACKAGES         =
259LATEX_HEADER           =
260LATEX_FOOTER           =
261PDF_HYPERLINKS         = YES
262USE_PDFLATEX           = YES
263LATEX_BATCHMODE        = NO
264LATEX_HIDE_INDICES     = NO
265LATEX_SOURCE_CODE      = NO
266LATEX_BIB_STYLE        = plain
267
268#---------------------------------------------------------------------------
269# configuration options related to the RTF output
270#---------------------------------------------------------------------------
271GENERATE_RTF           = NO
272RTF_OUTPUT             = rtf
273COMPACT_RTF            = NO
274RTF_HYPERLINKS         = NO
275RTF_STYLESHEET_FILE    =
276RTF_EXTENSIONS_FILE    =
277
278#---------------------------------------------------------------------------
279# configuration options related to the man page output
280#---------------------------------------------------------------------------
281GENERATE_MAN           = NO
282MAN_OUTPUT             = man
283MAN_EXTENSION          = .3
284MAN_LINKS              = YES
285
286#---------------------------------------------------------------------------
287# configuration options related to the XML output
288#---------------------------------------------------------------------------
289GENERATE_XML           = YES
290XML_OUTPUT             = xml
291XML_SCHEMA             =
292XML_DTD                =
293XML_PROGRAMLISTING     = NO
294
295#---------------------------------------------------------------------------
296# configuration options for the AutoGen Definitions output
297#---------------------------------------------------------------------------
298GENERATE_AUTOGEN_DEF   = NO
299
300#---------------------------------------------------------------------------
301# configuration options related to the Perl module output
302#---------------------------------------------------------------------------
303GENERATE_PERLMOD       = NO
304PERLMOD_LATEX          = NO
305PERLMOD_PRETTY         = YES
306PERLMOD_MAKEVAR_PREFIX =
307
308#---------------------------------------------------------------------------
309# Configuration options related to the preprocessor
310#---------------------------------------------------------------------------
311ENABLE_PREPROCESSING   = YES
312MACRO_EXPANSION        = YES
313EXPAND_ONLY_PREDEF     = YES
314SEARCH_INCLUDES        = YES
315INCLUDE_PATH           = /usr/users/lib/sys
316INCLUDE_FILE_PATTERNS  = *.h
317PREDEFINED             =
318EXPAND_AS_DEFINED      =
319SKIP_FUNCTION_MACROS   = YES
320
321#---------------------------------------------------------------------------
322# Configuration::additions related to external references
323#---------------------------------------------------------------------------
324TAGFILES               =
325GENERATE_TAGFILE       =
326ALLEXTERNALS           = YES
327EXTERNAL_GROUPS        = YES
328PERL_PATH              = /usr/bin/perl
329
330#---------------------------------------------------------------------------
331# Configuration options related to the dot tool
332#---------------------------------------------------------------------------
333CLASS_DIAGRAMS         = YES
334MSCGEN_PATH            =
335HIDE_UNDOC_RELATIONS   = NO
336HAVE_DOT               = YES
337DOT_NUM_THREADS        = 0
338DOT_FONTNAME           = Helvetica
339DOT_FONTSIZE           = 10
340DOT_FONTPATH           =
341CLASS_GRAPH            = YES
342COLLABORATION_GRAPH    = NO
343GROUP_GRAPHS           = YES
344UML_LOOK               = NO
345UML_LIMIT_NUM_FIELDS   = 10
346TEMPLATE_RELATIONS     = NO
347INCLUDE_GRAPH          = YES
348INCLUDED_BY_GRAPH      = YES
349CALL_GRAPH             = NO
350CALLER_GRAPH           = NO
351GRAPHICAL_HIERARCHY    = YES
352DIRECTORY_GRAPH        = NO
353DOT_IMAGE_FORMAT       = svg
354INTERACTIVE_SVG        = YES
355DOT_PATH               =
356DOTFILE_DIRS           =
357MSCFILE_DIRS           =
358DOT_GRAPH_MAX_NODES    = 50
359MAX_DOT_GRAPH_DEPTH    = 0
360DOT_TRANSPARENT        = NO
361DOT_MULTI_TARGETS      = YES
362GENERATE_LEGEND        = YES
363DOT_CLEANUP            = YES
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.
>