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

• The XHTML and JavaScript code are developed for the latest W3C-standards compliant browsers. Internet Explorer is not supported.
  It's not my intention to exclude 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.
  So, no support for IE, until it gets its act together.
  Browsers that have been tested: Opera 11.51, Firefox 6.02, Google Chrome 8.0.552.224, Safari 4.0.4 (531.21.10) and Konqueror 4.5.1
• Known browser issues:
• Some browsers don't support loading files using XMLHttpRequest on localhost.
  Because of this, features like showing the code of a symbol and viewing a tree of all symbols in the Symbols tab will not work.
  Workarounds:
• Chrome: Start the browser with this flag:
  $ google-chrome --allow-file-access-from-files
• Opera: Enable this option on the configuration page:
  opera:config#UserPrefs|AllowFileXMLHttpRequest
• Kandil tries to make use of the latest HTML5 features if available:
• Web Storage is used to store settings and to cache generated lists. Caching speeds up load times.
• The History object allows you to create a new history entry and also alter the URL in the address bar. This avoids loading the navigation bar again, when browsing a project's documentation. (Note: will be implemented once major browsers support it.)
• 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 code embedded 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.)
• Tokens in parameter lists and return types are highlighted (e.g. void f(ref p, char[] q = "str").
• 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.

FAQ

1. Download Dil and follow the instructions in the README to compile it.
2. Type bin/dil help ddoc to get help on how to use the command.
3. Try this example script:

#! /bin/bash
mkdir -p myproject_doc/ # Destination.

FILES=`find ~/path/to/myproject/src/ -iname '*.d'`

bin/dil ddoc myproject_doc/ $FILES -v --kandil -hl
# Run this script from the source dir of Dil.

By calling this script: scripts/html2pdf.py

See: example scripts.

Use the macros SYMLINK and SYMLINK2. E.g.:

1. $(SYMLINK Macro.this, Macro Constructor) would link to the symbol Macro.this in the current module.
2. $(SYMLINK2 dil.doc.Macro, Macro.this) would link to Macro.this in the module dil.doc.Macro.
3. $(SYMLINK3 dil.doc.Macro, Macro.this, see how to construct a Macro) is the same as SYMLINK3 but the 3rd argument changes the link text.

Filtering

There are 4 ways you can filter for symbols:

1. Plain text

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

Example: Expr will match "Expression", "AndExpression", "OrExpression" etc.

2. Fuzzy filtering

Entering a word followed by at least two dots will perform a search using the Levenshtein algorithm. The more dots you add the fuzzier the search will get (i.e. the Leven. distance is increased.)

Example: getname.... will match "name", "getDayName", "dayNames" etc.

3. FQN filtering

Use a dot to separate words in order to search for symbols by matching against their fully qualified names (FQN.)

Examples:
tango.math will match any symbol that is located in the math package.
.math. will show all math packages — if there are more than one — and the contained modules.

4. 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"...). You don't have to type out the complete name of the attribute.

Examples:
:ctor will show all constructors.
The string :pub (or ":publ", ":public") will search for symbols that have the public protection 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_KW
  The keyword of a D declaration (e.g. class, alias, auto etc.)
• DIL_ATTRIBUTES
• DIL_PROT
• DIL_STC
• DIL_LINKAGE
• DIL_PARAMS
• DIL_TEMPLATE_PARAMS
• DIL_BASECLASS
• DIL_BASECLASSES
• 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; to require explicit marking would have been better.

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.