[ news ] [ downloads ] [ plugins ] [ modules ] [ documentation ] [ info ]

DOG

• DOG is the TkScript document(ation) generator. It is used to generate HTML (and possibly other document format) pages from the raw documentation output emitted by the tks runtime if called with the -ee command line argument.
  The latest release (including some example code) is available here (11-Jan-2006). HTML formatted sources: dog.tks, dog_html.tks.
  • Documentation can be specified for modules, classes and functions/methods using the explain keyword.
    • Example:

      
      module Main;
      
      explain "The first line contains the short description (synopsis) for the current context.";
      
      function Test() {
        explain "Synopsis for function @this.";
      }
      
      class CTest {
        explain "Synopsis for class @this.";
      
        test() {
          explain "Synopsis for method @this";
        }
      
        static Test() {
          explain "Synopsis for function @this";
        }
      }
      

  • If the explain String contains multiple lines, lines 2..n are assumed to contain a comprehensive description for the current context object
  • The description ends at the end of the string OR at the first occurence of an attribute tag:
    • @arg argName desc : Used to describe an argument if the current context object is a function or method. The tag may occur at most one time for each argument.
    • @author string : Used to specify the author of the given object. The tag may occur 0..1 times.
    • @date string : Used to describe the history of the given object. The tag may occur 0..n times.
    • @deprecated reason : Used to mark the current context object as outdated (i.e. not to be used anylonger in new code). Currently only allowed for functions and methods. The tag may occur 0..1 times.
    • @return desc : Used to describe the return type if the current context object is a function or method. The tag may occur 0..1 times.
    • @since version : Used to specify since when the current context object has been available. Currently only allowed for functions and methods. The tag may occur 0..1 times.
  • The special string @this will be replaced by the name of the current context object
  • The following HTML tags are allowed:
    • b, big, br, code, i, li, ol, p, pre, small, u, ul
    • no attributes may be specified
  • Includes have the following syntax: `<filename>`.
    • Includes may be used recursively. In order to detect an infinite recursion the maximum text size is limited to 2 MBytes.
    • Includes are used to include figures, complex HTML or recurring paragraphs.
  • Line breaks are handled in the following way:
    • A single empty line is replaced by <br>
    • Two or more consecutive empty lines are replaced by <br>&nbsp;<br>
  • Quicklinks are used to insert a hyperlink to another context object (excerpt from dog/test.tks):
    • link to a function in this class : §Test_NoArgsVarRet
    • link to a method in this class: §test_argsIntRet
    • link to a module : §MTestModule2
    • link to a module function : §MTestModule1.Test
    • link to a module class : §MTestModule1.CTestMod1
    • link to a class function: §CTestMod1.AddIntegers
    • fully qualified link to a class method: §MTestModule1.CTestMod1.test1
  • The HTML files are created by calling tks -ee <myscript> | tks dog (assuming that dog.tkx/dog.tkp is in the current path)
    • Example input: test.tks
    • Example output: test, ui

  ---