ADOC

(Hide table-of-contents)

ADOC is part of the CategoryAplTree project.

ADOC was discussed in detail in this article on Vector from 2012 but that article is now outdated.

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 won't see the forest for trees. 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 page from them.

2. How to get ADOC

If you are using Dyalog 16.0 or better you have it already at your disposal. It became an official Dyalog user command with version 16.0

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

3. How to use ADOC

It is strongly recommended to use ADOC as a user command; a user command script is part of the download.

See UserCommands/WhereShouldTheyGo for details how to make ADOC available as a user command.

4. Process #.ADOC with #.ADOC

When you execute

      ]???ADoc 

ADOC processes itself. Since ADOC takes advantage of pretty much all features itself it acts as a kind of self-reference.

4.1. Summary

Assuming that you have the APLTree class OS in your workspace:

      ]adoc OS -summary
*** OS (Class) ***

Shared Methods:
  CreateParms_WinExecute
  GetPID
  GetSharedLib
  History
  KillPID
  ShellExecute
  Version
  WinExecBatch
  WinExecute

In case you are interested even in the headers of these methods:

      ]ADoc ⎕se.OS -summary=full
*** OS (Class) ***

Shared Methods:
  parms ← CreateParms_WinExecute
  r ← GetPID
  r ← GetSharedLib
  History
  r ← KillPID pid
  (rc more result) ← ShellExecute cmd
  r ← Version
  (success rc result) ← {adminFlag} WinExecBatch cmd
  {(success rc more)} ← {adminFlag} WinExecute x

4.2. Fully-fledged documentation

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

      ]ADoc OS

You can specify more than one class, interface and namespace:

      ]ADoc Overview APLTreeUtils FilesAndDirs OS

5. An Example

Look here for an example of what ADOC is generating when processing itself:

ADOC.HTML

You need to download the HTML file and then view it with your browser.

Notes:

6. Project Page

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

7. Version Information

Original author:

KaiJaeger

Responsible:

KaiJaeger

Email:

kai@aplteam.com

8. APLTree downloads

8.1. Using an APLTree member

  1. If you just want to consume (use) an APLTree member then you have several choices:
    • Note that accessing it via ftp allows you to download older versions as well while the dedicated download page offers just the most current version.

8.2. Contributing

If you want to contribute to an APLTree project see HowToContributeToTheAPLTreeProject for details.

8.3. Get the full project

If for some reason you need access to, say, the test cases then you need to get more then just the script (or application) itself.

HowToContributeToTheAPLTreeProject explains how to get a project onto your local machine. Just ignore any additional steps.

8.4. Create a new APLTree sub project

In order to create a new APLTree project you need some advice. Ask KaiJaeger for help: mailto:kai@aplteam.com


CategoryAplTree

ADOC (last edited 2017-06-27 09:47:53 by KaiJaeger)