Kandil

Kandil is an XHTML and JavaScript browser application for documentation generated by dil.

Ddoc is used as the underlying system to generate the documentation. Dil improves upon Ddoc with unique features and introduces small differences:

Features

• Developed for W3C-standards compliant browsers, which doesn't include Internet Explorer.
  It's not my intention to be mean to IE users, but the fact of the matter is that it costs a lot of energy and nerves to code for Microsoft's browsers.
  Even coding only for the "good" browsers is sometimes difficult enough.
  However, after having taken a short look at the promising improvements in IE8, I will consider supporting it.
  Browsers that have been tested: Opera 9.64, Firefox 3.0.10, Google Chrome 1.0.154.36, Safari 4.0 (530.17) and Konqueror 4.2.2
• Display the source code of a symbol when clicked.
• The symbol and module list in the navigation bar can be filtered.
• Every symbol in the document is targetable using a URL fragment.
  E.g.: url/dil.doc.Macro.html#Macro.this
• Superfluous indentation is removed from embedded code in comments.
• Every symbol can be linked to its source location (a repository or a local HTML file.)
• Protection, linkage and storage class attributes are shown in brackets.
• Report warnings for undefined macros and unterminated macros (missing closing ')'.)
• Every token in a code section is highlighted (customizable via kandil/style.css and data/html_map.d.)
• Undocumented symbols can be included in the documentation using the '-i'-switch.
• Unicode alphas are supported in macro, section and parameter names.
• Not strictly a feature of kandil, but html2pdf.py can generate PDF documents using PrinceXML.

Filtering

There are three ways you can filter for specific symbols:

Plain text

Enter letters or words as usual, and a list of symbols that match will be shown. For example, "Expr" will match "Expression", "AndExpression", "OrExpression" etc.
You can also put a wildcard between two strings, e.g. "parse*ion" will match "parseExpression".

FQN filtering

Use a dot to separate words in order to search for symbols by matching against their fully qualified names (FQN.) For example, "tango.math" will match any symbol that is located in the math package. Or ".math." will show all math packages - if there are more than one - and the contained modules.

Attribute filtering

Strings that start with a colon, ":", will search for symbols by matching against their attributes. Attributes can be symbol kinds (e.g. "variable", "function"...) and storage classes (e.g. "extern", "protected"...). For example, the strings ":pub", ":publ", ":public" will search for symbols that have the public protection attribute. You don't have to type out the complete name of the attribute.

Macros

This is a list of macros which are only defined by dil.

• DIL_SYMBOL (replaces DDOC_PSYMBOL)
  Five Parameters:
1. Symbol name (e.g. "this")
2. Fully qualified name excluding the module's FQN (e.g. "Macro.this", MODFQN = "dil.doc.Macro")
3. Symbol kind (e.g. "ctor")
   Values: template, class, interface, struct, union, alias, typedef, enum, enummem, function, variable, invariant, new, delete, unittest, ctor, dtor, sctor, sdtor
4. Begin line number in the code (e.g. 19)
5. End line number in the code (e.g. 23)
• DIL_MODFQN (e.g. "dil.doc.Macro")
• DIL_MODPATH (e.g. "dil/doc/Macro.d")
• DIL_DOCFILENAME (e.g. "dil.doc.Macro.html")
• DIL_ATTRIBUTES
• DIL_PROT
• DIL_STC
• DIL_LINKAGE
• DIL_PARAMS
• DIL_TEMPLATE_PARAMS
• DIL_BASE_CLASSES
• DDOC_AUTHOR (singular of existing DDOC_AUTHORS)
• DIL_SC: a semicolon after a declaration.

Shortcomings

In contrast to dmd, dil doesn't highlight some keywords (e.g. null) and it doesn't emphasize symbols found in the comment text. In my experience, this is more trouble than desirable, explicit marking would have been better. Nevertheless, this might be implemented using JavaScript.

Variables/parameters with a DeclaratorSuffix (e.g. "int a[]") are slightly problematic (use "int[] a" instead.)

Sometimes it is apparent that semantic information is lacking. Furthermore, static if-statements are not evaluated (the if-branch is always chosen by default,) since SA in dil is not advanced enough, even for evaluating simple expressions.