wiki/kandil.wiki

   1 #summary Kandil is the magic oil-lamp that manifests your documentation wishes.
   2
   3 = Kandil =
   4 Kandil is an XHTML and !JavaScript browser application for documentation
   5 generated by dil.
   6
   7 Ddoc is used as the underlying system to generate the documentation.
   8 Dil improves upon Ddoc with unique features and introduces small differences:
   9
  10 == Features ==
  11   * Display the source code of a symbol when clicked.
  12   * Every symbol in the document is targetable using a URL fragment.<br>E.g.: `url/dil.doc.Macro.html#Macro.this`
  13   * Superfluous indentation is removed from embedded code in comments.
  14   * Every symbol can be linked to its source location (a repository or a local HTML file.)
  15   * Protection, linkage and storage class attributes are shown in brackets.
  16   * Report warnings for undefined macros and unterminated macros (missing closing ')'.)
  17   * Every token in a code section is highlighted (customizable via kandil/style.css and data/html_map.d.)
  18   * Undocumented symbols can be included in the documentation using the '-i'-switch.
  19   * Unicode alphas are supported in macro, section and parameter names.
  20
  21 == Macros ==
  22   * DIL_SYMBOL (replaces DDOC_PSYMBOL)<br>Five Parameters:
  23       # Symbol name (e.g. "this")
  24       # Fully qualified name excluding the module's FQN (e.g. "Macro.this", MODFQN = "dil.doc.Macro")
  25       # Symbol kind (e.g. "ctor")<br>Values: `template, class, interface, struct, union, alias, typedef, enum, enummem, function, variable, invariant, new, delete, unittest, ctor, dtor, sctor, sdtor`
  26       # Begin line number in the code (e.g. 19)
  27       # End line number in the code (e.g. 23)
  28   * DIL_MODFQN      (e.g. "dil.doc.Macro")
  29   * DIL_MODPATH     (e.g. "dil/doc/Macro.d")
  30   * DIL_DOCFILENAME (e.g. "dil.doc.Macro.html")
  31   * DIL_ATTRIBUTES
  32   * DIL_PROT
  33   * DIL_STC
  34   * DIL_LINKAGE
  35   * DIL_PARAMS
  36   * DIL_TEMPLATE_PARAMS
  37   * DIL_BASE_CLASSES
  38   * DDOC_AUTHOR (singular of existing DDOC_AUTHORS)
  39
  40 == Shortcomings ==
  41 In contrast to dmd, dil doesn't highlight some keywords (e.g. null) and it
  42 doesn't emphasize symbols found in the comment text. In my experience, this
  43 is more trouble than desirable, explicit marking would have been better.
  44 Nevertheless, this might be implemented using !JavaScript.
  45
  46 Variables/parameters with a !DeclaratorSuffix (e.g. "`int a[]`") are slightly
  47 problematic (use "`int[] a`" instead.)
  48
  49 Sometimes it is apparent that semantic information is lacking.