ADOC

ADOC is part of the CategoryAplApl project.

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.

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.

How to get ADOC

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

Load the CLass

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

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

Process #.ADOC with #.ADOC

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

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

The "Browse" Command

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

ADOC.Browse ADOC 'firstTry.html'

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.

History

For a full version history: History

Version Information

Download

You have two options: you can either download the script for usage:

Download ADOC script right now

or get the whole thing from the AplWikiRepository, including the development workspace and the script and maybe more for any development or for running the test cases:

svn list svn://aplteam.com/os/dyalog/ADOC/tags

If you plan to contribute please note that all stuff published as part of the APLAPL project must follow certain APLAPL-specific standards.

CategoryAplApl