ADOC

(Show (Hide table-of-contents) table-of-contents)

ADOC is part of the CategoryAplTree project.

ADOC is discussed in detail in this article on Vector from 2012.

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 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 in order to take advantage of OO you should look only at the public stuff.

All fields, properties and methods of type Instance remain invisible until you create an instance. In order to create an instance you might need the documentation.

ADOC extracts all sorts of information from a class or interface no matter whether they are of type Instance or Shared and compiles an HTML from them.

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:

]Load 'C:\Dyalog\...\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)
  ...
Instance Properties:
  htmlFinalised (ReadOnly)
  ...
Shared Properties:
  BrowserName
  ...
Shared Fields:
  _Caption
  ...
Instance Methods:
  Analyze
  ...
Shared Methods:
  Browse
  ...

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)
  ...
Instance Properties:
  htmlFinalised (ReadOnly)
  ...
Shared Properties:
  BrowserName
  ...
Shared Fields:
  _Caption
  ...
Instance Methods:
  {embeddedClassName} Analyze scriptName
  ...
Shared Methods:
  {x} Browse scriptRef
  ...

5.3. The "Browse" Command

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

ADOC.Browse ADOC

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 allow you to make ADOC suit your needs.

7. ADOC as a Dyalog User Command

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

8. Project Page

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

9. Version Information

CategoryAplTree