Generate documentation

[user24461]

The openedge-project.json file has "documentation" attributes, but how can these documents be generated? And what do you have to install to be able to generate these documents?

  "buildPath": [
    // Entries can have type 'source' or 'propath'. Path attribute is mandatory. Build attribute is optional (defaults to 'path'). Xref attribute is optional (defaults to 'build/.pct' or '.builder/srcX')
    { "type": "source", "path": "src/procedures" },
    { "type": "source", "path": "src/classes" },
    // Include and exclude patterns are case-insensitive on Windows, and case-sensitive on any other operating system
    { "type": "source", "path": "src/dev", "includes": "foo/**,bar/**", "excludes": "foo/something/**" },
    { "type": "propath", "path": "${DLC}/tty/netlib/OpenEdge.net.pl", "documentation": "openedge.json" }     <== documentation attribute
  ],

[gquerret]

You can use the JsonDocumentation task on the Progress ADE project.

<?xml version="1.0"?>
<project name="ADE">
  <taskdef resource="PCT.properties" />
  <typedef resource="types.properties" />
  <mkdir dir="db" />
  <PCTCreateDatabase destDir="db" dbName="sample" structFile="sample.st" schemaFile="sample.df" dlcHome="${DLC}" auditing="true" auditArea="area1" auditIndexArea="area2" tablePartitioning="true" cdc="true" cdcArea="area1" cdcIndexArea="area2" />

  <DBConnection dbDir="db" dbName="sample" singleUser="true" id="tmpdb">
    <Alias name="stsdb" />
  </DBConnection>
  <path id="pp">
    <pathelement location="businesscomponents" />
    <pathelement location="corelib" />
    <pathelement location="netlib" />
    <pathelement location="seclib" />
    <pathelement location="." />
  </path>


  <JsonDocumentation buildDir="build" destFile="corelib.json" dlcHome="${DLC}" encoding="iso-8859-1" indent="true">
    <fileset dir="corelib" includes="**/*.cls" />
    <DBConnection refid="tmpdb" />
    <propath refid="pp" />
  </JsonDocumentation>
  <JsonDocumentation buildDir="build" destFile="netlib.json" dlcHome="${DLC}" encoding="iso-8859-1" indent="true">
    <fileset dir="netlib" includes="**/*.cls" />
    <DBConnection refid="tmpdb" />
    <propath refid="pp" />
  </JsonDocumentation>
  ... and so on ...
</project>

[user24461]

Thanks, the doc's for netlib, corelib en businesscomponents are generated now.

It is important that the buildDir points to the r-files. First I only got the names of the cls-files.

`

<property environment="env"/>

<taskdef resource="PCT.properties" classpath="${env.DLC}/pct/PCT.jar" />
<typedef resource="types.properties" classpath="${env.DLC}/pct/PCT.jar" />
    
<mkdir dir="doc" />
<mkdir dir="db" />

<PCTCreateDatabase destDir="db" dbName="sample" structFile="sample.st" schemaFile="sample.df" dlcHome="${env.DLC}" auditing="true" auditArea="area1" auditIndexArea="area2" tablePartitioning="true" cdc="true" cdcArea="area1" cdcIndexArea="area2" />

<JsonDocumentation buildDir="ADE/netlib" destFile="doc/netlib.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
    <fileset dir="ADE/netlib" includes="**/*.cls"/>
    <DBConnection dbDir="db" dbName="sample" singleUser="true" id="tmpdb"/>
    <propath>
        <pathelement location="ADE/netlib" />
        <pathelement location="ADE/corelib" />
        <pathelement location="ADE/businesscomponents" />
        <pathelement location="." />
    </propath>
</JsonDocumentation>

<JsonDocumentation buildDir="ADE/corelib" destFile="doc/corelib.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
    <fileset dir="ADE/corelib" includes="**/*.cls"/>
    <DBConnection dbDir="db" dbName="sample" singleUser="true" id="tmpdb"/>
    <propath>
        <pathelement location="ADE/netlib" />
        <pathelement location="ADE/corelib" />
        <pathelement location="ADE/businesscomponents" />
        <pathelement location="." />
    </propath>
</JsonDocumentation>

<JsonDocumentation buildDir="ADE/businesscomponents" destFile="doc/businesscomponents.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
    <fileset dir="ADE/businesscomponents" includes="**/*.cls"/>
    <DBConnection dbDir="db" dbName="sample" singleUser="true" id="tmpdb"/>
    <propath>
        <pathelement location="ADE/netlib" />
        <pathelement location="ADE/corelib" />
        <pathelement location="ADE/businesscomponents" />
        <pathelement location="." />
    </propath>
</JsonDocumentation>

`

[gabsoftware]

Hi Gilles,

What's the content of sample.st and sample.df? Where do we find those? It is unclear how to generate those documentation files correctly.

update:

sample.st:

b .
d "Schema Area":6,32 .
d "area1":7,32;8 .
d "area2":8,32;8 .

sample.df:

ADD TABLE "Placeholder"
  AREA "Schema Area"
  DESCRIPTION "Placeholder"
  DUMP-NAME "placeholder"

[gabsoftware]

I think I got it... I compiled the classes into the build folder before running the JsonDocumentation tasks.

[gabsoftware]

Here is the full tasks file that I used, it might be useful to some:

<?xml version="1.0"?>
<project name="ADE" default="documentation">
    <property environment="env"/>

    <taskdef resource="PCT.properties" classpath="${env.DLC}/pct/PCT.jar" />
    <typedef resource="types.properties" classpath="${env.DLC}/pct/PCT.jar" />

    <DlcHome value="${env.DLC}" />
        
    <mkdir dir="doc" />
    <mkdir dir="db" />
    <PCTCreateDatabase destDir="db" dbName="sample" structFile="sample.st" schemaFile="sample.df" dlcHome="${env.DLC}" auditing="true" auditArea="area1" auditIndexArea="area2" tablePartitioning="true" cdc="true" cdcArea="area1" cdcIndexArea="area2" />

    <DBConnection dbDir="db" dbName="sample" singleUser="true" id="tmpdb">
        <Alias name="stsdb" />
    </DBConnection>

    <path id="pp">
        <pathelement location="ablunit" />
        <pathelement location="businesscomponents" />
        <pathelement location="corelib" />
        <pathelement location="netlib" />
        <pathelement location="seclib" />
        <pathelement location="." />
    </path>

    <target name="compilation" description="compilation of netlib, corelib, seclib and businesscomponents">
        <PCTCompile destDir="build" paramFile="pct.pf" stopOnError="false" forceCompile="true" progPerc="10" multiCompile="true">
            <fileset dir="netlib" includes="**/*.cls"/>
            <fileset dir="corelib" includes="**/*.cls"/>
            <fileset dir="businesscomponents" includes="**/*.cls"/>
            <fileset dir="seclib" includes="**/*.cls"/>
            <fileset dir="ablunit" includes="**/*.cls"/>
            <DBConnection refid="tmpdb" />
            <propath refid="pp" />
        </PCTCompile>
    </target>

    <target name="documentation" description="generating documentation of netlib, corelib, seclib and businesscomponents" depends="compilation">
        <JsonDocumentation buildDir="build" destFile="doc/netlib.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
            <fileset dir="netlib" includes="**/*.cls"/>
            <propath refid="pp" />
        </JsonDocumentation>

        <JsonDocumentation buildDir="build" destFile="doc/corelib.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
            <fileset dir="corelib" includes="**/*.cls"/>
            <propath refid="pp" />
        </JsonDocumentation>

        <JsonDocumentation buildDir="build" destFile="doc/seclib.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
            <fileset dir="seclib" includes="**/*.cls"/>
            <DBConnection refid="tmpdb" />
            <propath refid="pp" />
        </JsonDocumentation>

        <JsonDocumentation buildDir="build" destFile="doc/businesscomponents.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
            <fileset dir="businesscomponents" includes="**/*.cls"/>
            <propath refid="pp" />
        </JsonDocumentation>

        <JsonDocumentation buildDir="build" destFile="doc/ablunit.json" dlcHome="${env.DLC}" encoding="iso-8859-1" indent="true">
            <fileset dir="ablunit" includes="**/*.cls"/>
            <propath refid="pp" />
        </JsonDocumentation>
    </target>
</project>

I had to patch line 146 of corelib\OpenEdge\Core\EncodedString.cls:

--- a/corelib/OpenEdge/Core/EncodedString.cls
+++ b/corelib/OpenEdge/Core/EncodedString.cls
@@ -143,7 +143,7 @@
             else if lookup(string(mEncoding), EncodedString:EncodingNames) gt 0 then do:
                 // Allow any valid encoding prefix (encryption algorithm) in the list of non-retired options.
                 {&_proparse_ prolint-nowarn(overflow)}
-                assign this-object:Value = audit-policy:encrypt-audit-mac-key(string(this-object:Value), string(mEncoding)).
+                assign this-object:Value = audit-policy:encrypt-audit-mac-key(string(this-object:Value)).
             end.
             else
                 // If we are unable to encode the value in ABL, throw an error. [Should never get here, but regardless...]

[gquerret]

The repository with the build file is available here.

[gabsoftware]

Ah thank you ! 👍