ADOC

ADOC is part of the CategoryAplTree project.

1. Overview

With OO in Dyalog APL, the demand for documentation is increasing.

How's that? Well, objects are designed to act as 'black boxes'. They offer methods and properties and fields (hopefully well designed) that let the user manipulate data without understanding all (or even any) details of the implementation.

But how to find out what can be used? Looking into the script, or using the Tracer when using a class is definitely not a good idea: you see everything, but you should look only at the public stuff.

There is obviously a need for some kind of documentation standard. Hence ADOC. At the end of the document you can see what ADOC is generating by processing itself.

For more information see GeneratingDocumentations.

2. Pre-Conditions

The ADOC class needs the "UnicodeFile" Dyalog Version 11 ships with. ADOC assumes that this class is available in either ⎕SE or #. With version 2.3 ADOC became 100% self-contained.

3. How to get ADOC

At the end of this page you can find the download links.

4. Load the CLass

To start, load the class with SALT, for example:

⎕SE.SALT.Load 'C:\Dyalog\V110\Classes\ADOC\ADOC'

5. Process #.ADOC with #.ADOC

5.1. The "List" Command

Now you can ask ADOC to document itself. To get a short list of the public interface:

      ADOC.List ADOC
*** ADOC (Class) ***

Constructors:
  make_1(fullDocName)
  make_2(fullDocName caption)
  make_0
  make_all all
Instance Properties:
  htmlFinalised (ReadOnly)
  Creator
  FullDocName
  HTML
  IncludeStylesheets
  Meta (ReadOnly)
  OutputType
  WithRunningNumbers
Shared Properties:
  BrowserName
  BrowserPath
  Caption
  IgnorePattern
  Inherit
Shared Fields:
  _Caption
  nl
  MaxWidthInChars
Instance Methods:
  Analyze
  CreateDocFooter
  CreateHtml
  CreateTopOfBody
  FinaliseHtml
  Make
  Reset
  SaveHtml2File
Shared Methods:
  Browse
  Copyright
  Help
  History
  List
  MakeScriptFromNamespace
  ProcessAsHtml
  ReportEmbeddedClasses
  Version
  View

5.2. The "'Full' List" Command

You can ask ADOC about the syntax of the methods by specifying a left argument:

      'full' ADOC.List ADOC
*** ADOC (Class) ***

Constructors:
  make_1(fullDocName)
  make_2(fullDocName caption)
  make_0
  make_all all
Instance Properties:
  htmlFinalised (ReadOnly)
  Creator
  FullDocName
  HTML
  IncludeStylesheets
  Meta (ReadOnly)
  OutputType
  WithRunningNumbers
Shared Properties:
  BrowserName
  BrowserPath
  Caption
  IgnorePattern
  Inherit
Shared Fields:
  _Caption
  nl
  MaxWidthInChars
Instance Methods:
  {embeddedClassName} Analyze scriptName
  CreateDocFooter dummy
  CreateHtml dummy
  CreateTopOfBody dummy
  FinaliseHtml dummy
  {filename} ← Make scripts
  Reset
  {filename} ← SaveHtml2File filename
Shared Methods:
  {x} Browse scriptRef
  r ← Copyright
  r ← Help
  r ← History
  r ← {verbose} List scriptName
  script ← scriptName MakeScriptFromNamespace name
  ProcessAsHtml(scripts filename)
  r ← ReportEmbeddedClasses refToClass
  r ← Version
  View filename

5.3. The "Browse" Command

To display the fully-fledged documentation as an HTML page with your default browser:

ADOC.Browse ADOC 'firstTry.html'

6. An Example

Look here for an example of what ADOC is generating then:

http://misc.aplteam.com/ADOC.HTML

Note that all the information in this example is derived from the class script itself.

Note that there are lots of methods and properties available that allows you to make ADOC suit your needs.

7. Other output format

With version 3.0 ADOC can be used to create a bunch of different output formats. In order to achieve this it needs the third-party-software HelpAndManual as well as the classes belonging to APL2XML. For more details see there. APL2XML is part of the APLTree Open Source project.

The output formats supported by HelpAndManual:

• Compiled Help
• Windows Help (okay, outdated)
• HTML Help
• Visual Studio Help
• RTF
• PDF
• Electronic Books

8. ADOC as a Dyalog User Command

ADOC can be used as a User Command. For details see UserCommands/ADOC.

9. Project Page

For bug reports, future enhancements and a full version history see ADOC/ProjectPage

10. Version Information

CategoryAplTree