aplteam / adoc Goto Github PK

Automated documentation generation for Dyalog APL

License: MIT License

APL 100.00%

apl dyalog-user-command documentation-generator dyalog-apl

adoc's Introduction

ADOC

ADOC stand for Automated DOCumentation. It analyzes Dyalog APL Classes, Interfaces and namespaces, scripted as well as non-scripted ones, and generates documentation from them. That documentation can be enriched by adding Markdown to the Class, Interface or namespace script as comments.

Requirements

ADOC requires Dyalog APL 18.0 Unicode or better.

Samples

      ]ADoc -?
───────────────────────────────────────────────────────────────────────────────
                                                                               
]TOOLS.ADoc                                                                    
Source: /path/to/ADOC_uc.dyalog                          
Version: 2.391                                                                 
Syntax:                                                                        
Accepts modifiers -browser= -ref= -summary[=] -title= -toc= -filename= -version           
 Modifier 'ref' accepts values consisting only of characters in the set "0 1"  
 Modifier 'summary' accepts only values "full"                                 
 Modifier 'toc' accepts values consisting only of characters in the set "0 1"  
                                                                               
Automated documentation generation                                             
]ADoc -??  ⍝ for syntax details                                                
]ADoc -??? ⍝ to view the complete ADoc documentation in a browser window       
                                                                               

      ]ADoc -??
───────────────────────────────────────────────────────────────────────────────                                           
]TOOLS.ADoc

Source: /path/tpADOC_uc.dyalog                                                                    
Version: 2.391

Syntax:

Accepts modifiers -browser= -ref= -summary[=] -title= -toc= -filename= -version

 Modifier 'ref' accepts values consisting only of characters in the set "0 1"
 Modifier 'summary' accepts only values "full"
 Modifier 'toc' accepts values consisting only of characters in the set "0 1"
 Modifier Default is a temp filename but allows any filename

Gathers information about one or more classes and/or namespaces.                                                          

Either compiles an HTML page which is then displayed in a browser (default) or prints
summarizing information to the session (-summary).

 -title={text}    Add a custom title with the content {text}
 -browser={path}  Use the non-default browser specified
 -summary[=full]  Returns summarized information about the object members (optionally including full function headers)
 -version         Returns the version number of ADOC used. If specified everythings else is ignored

When objects are not addressed with a full name (= start neither with `#` nor with `⎕SE` then the user command will try to find the     
objects in the namespace the user command was called from. If they cannot be found there it will assume they live in `#`.               

Examples:                                                                                                                               
    ]ADoc MyClass                              ⍝ single class
    ]ADoc MyClass FilesAndDirs                 ⍝ two classes                                  
    ]ADoc MyClass -title="My Doc"              ⍝ custom title
    ]ADoc MyClass -browser="c:\opera.exe"      ⍝ custom browser
    ]ADoc MyClass -summary                     ⍝ basic info
    ]ADoc MyClass -summary=full                ⍝ more detailed info                           

]ADoc -??? ⍝ to view the complete ADoc documentation in a browser window

ADOC as a User Command

With version 16.0 ]ADOC became an official Dyalog user command.

adoc's People

Contributors

Stargazers

Watchers

adoc's Issues

ADOC crashes on invalid result of user's Public function

A function Public that exists in a namespace is expected to return a vector of text vectors defining the names of everything that is public within that namespace.

That works fine, but when Public returns a simple text matrix it crashes ADOC. It should process a simple text matrix in the same way.

Replace default namespace/class captions

By default there is no main caption but it can be set with -title=.

By default sub-titles are created from the name of the namespace or class ADOC is processing.

Currently there is no way to replace those defaults. In rare cases one wants to.

An example is ]CodeBrowser -???: this works on ⎕SE._CodeBrowser resulting in the title _CodeBrowser. A better title would be CodeBrowser of course.

ADOC's documentation regarding ordinary namespace is wrong

The examples for a variable and a function ADOC_Doc is invalid.

Rather than ]ADoc #.Temp.Doc it should have been ]ADoc #.Temp.

ADOC has no API - it should

Change CSS for tables with less than four rows

Changing colours for alternating rows in a table improves readability greatly, but not when the table has only three or (worse) two columns.

ADOC could create nothing but Markdown

Consider creating pure Markdown in a first step which is then converted into HTML5 with MarkAPL at the very end, and only as the default.

This could allow converting the Markdown into something else.

When a function is specified rather than a namespace the message provided is not helpful

At least for non-niladic functions.

We should perform a very early check on the name class: functions are not supported, and we should say so.

ADOC should use Tatin packages

Currently ADOC is delivered as a workspace, and all that's required by ADOC is copied from that WS.

It should depend on packages, and only import the ADOC script when required.

Major bug: The complete Reference has disappeared from the TOC

ADOC_Doc should be ignored

When ADOC_Doc exists in an ordinary namespace #.foo the command

]adoc #.foo

lists ADOC_Doc in the Reference part of the documentation.

Headers have a problem with APL code

A header that consist of just APL chars does not make it into the TOC at all
A header that contains some APL would not show the APL characters

Allow vectors of text vectors for ordinary namespaces

For ordinary namespaces ADOC uses the reserved name ADOC_Doc. If that exists it is supposed to be a niladic function that carries nothing but comments.

Allow as an alternative ADOC_Doc to be a vector of text vectors.

That would have the same result but it does not require the leading ⍝ on every line. That would make editing easier.

The "Reference" part should not show at all if there is nothing to report

Leading comments of ADOC need proofreading

Typos
The header "ADOC as a user command" does not make sense with its first paragraph.

ADOC has no way to display an image?!

Needs to be investigated