ClassDocumentation does not know about generic types like Progress.Collections.IList<T>

[PeterJudgeZA]

If a class has members that have a type of Progress.Collections.IList<> , or return/consume such values, the XML file created by the ClassDocumentation does not write appropriate values.

    <property name="NativeList" dataType="UNKNOWN DATATYPE" isAbstract="false" isStatic="false" isOverride="false" extent="0" getModifier="PUBLIC" setModifier="PUBLIC">
        <propertyComment>/**&#13;
     * Purpose: The native/built-in List&lt;T&gt; that stores items&#13;
     * Notes:&#13;
     *&#13;
     */</propertyComment>
    </property>

    <method methodName="GetGenericEnumerator" signature="GetGenericEnumerator()" isStatic="false" isFinal="false" isAbstract="false" isOverride="false">
        <methodComment>/**&#13;
     * Purpose: Returns a native Progress.Collections.IIterator&lt;T&gt; instance for this list&#13;
     * Notes:&#13;
     * @return The Progress.Collections.IIterator&lt;T&gt; instance for this object&#13;
     */</methodComment>
    </method>

For the property, note the UNKNOWN DATATYPE, and that for the method's signature, the return type is missing completely.

To Reproduce Create a class similar to the below.

CLASS ListHolder:
    /**
     * Purpose: The native/built-in List<T> that stores items
     * Notes:
     *
     */
    DEFINE PRIVATE PROPERTY NativeList AS Progress.Collections.IList<Progress.Lang.Object> NO-UNDO
    GET():
        IF NOT VALID-OBJECT(THIS-OBJECT:NativeList) THEN
            THIS-OBJECT:NativeList = NEW Progress.Collections.List<Progress.Lang.Object>().

        RETURN THIS-OBJECT:NativeList.
    END GET.
    SET.

    /**
     * Purpose: Returns a native Progress.Collections.IIterator<T> instance for this list
     * Notes:
     * @return The Progress.Collections.IIterator<T> instance for this object
     */
    METHOD PUBLIC Progress.Collections.IIterator<Progress.Lang.Object> GetGenericEnumerator():
        RETURN THIS-OBJECT:NativeList:GetIterator().
    END METHOD.
END CLASS.

Expected behavior The ABL datatype should be correctly reflected in the generated XML.

Environment

• Windows 11 64bit
• OpenEdge 12.5.1
• Ant 1.10.5
• PCT 221 and 222

Additional context In my particular case the property and method definition is in an include, but I would not expect that to make a difference.

[gquerret]

It's time to move on and start using JsonDocumentation, as that will be based on two components that are actively maintained (rcode-reader and proparse). We can talk about that during the PUG Challenge.

[DustinGrau-PSC]

Good call, I had just noticed this as well that there's no return type when you have something like List<String> defined as the type.

Could I also ask if any of the existing documentation options support returning the input or output mode for parameters to a class method? Does the AST even report a method parameter's mode, or just the name and datatype? If the AST supports it but ABLDuck and PCTDoc do not use it, does the JsonDocumentation utilize it to properly describe parameters?

[gquerret]

Won't fix, use JsonDocumentation task. I confirm that the generics information is available there, as well as the input/output mode.

[DustinGrau-PSC]

What does the JsonDocumentation provide that ClassDocumentation does not? Is there a UI wrapper to the produced JSON?

[gquerret]

ClassDocumentation won't be maintained anymore (at least not by Riverside). Multiple reasons for that:

• it depends on ast.jar which is much more difficult to maintain than proparse
• entirely depends on the parser, when JsonDoc first depends on rcode structure (more precise) and then attach the comments
• JsonDoc is already used in the language server

And no, there's no UI wrapper to the produced JSON. The existing class documentation tasks (ClassDoc and ABLDuck) can be migrated to use the Json output, pull requests are welcome (see #461).

[DustinGrau-PSC]

This is very useful to know regarding the maintenance going forward on ClassDoc and why. Is there a usable example which shows how the JsonDoc should be used and how to consume the results? I've found some of the documentation to be lacking in actual demonstrations of behavior (a shared concern of our own, understandably).

[gquerret]

Is there a usable example which shows how the JsonDoc should be used and how to consume the results?

Documentation: https://wiki.rssw.eu/pct/JsonDocumentation.md No example on how to consume the result. @spazzymoto Did you push the updated ABLDuck code somewhere ?

[DustinGrau-PSC]

This is where it breaks down. I've followed the documentation to the best of my knowledge, and I have a directory with R-code, supplied a fileset and propath, and nothing is generated. I get a single JSON file with just an empty array. If there's a better way to discuss this, I would expect others to eventually run into the same situation if this is the future of documentation going forward.

    <JsonDocumentation
        destFile ="${build.html}/json/doc.json"
        buildDir ="${build.root}/rcode"
        encoding="UTF-8"
        indent="true">
        <fileset dir="${build.root}/rcode">
            <include name="**/*.p"/>
            <include name="**/*.cls"/>
        </fileset>
        <propath>
            <pathelement path="${build.root}/rcode"/>
        </propath>
    </JsonDocumentation>

[gquerret]

<fileset dir="${build.root}/rcode">

Mistake is probably here ; you have to point to the source directory (in order to execute the parser)

[DustinGrau-PSC]

I may be unclear on what "source" means in this case. Since the Proparse was described as needing the r-code, I assume the source here is not the original .p or .cls files, but something else?

[gquerret]

@DustinGrau-PSC Comments are not available from the rcode, so source code is needed. RCode contains the exact structure (even method signatures with .net types), so all methods / properties / ... are extracted from rcode. Then the parser is executed on the source code, and comments are attached to the right method.

I may be unclear on what "source" means in this case

Just the source code of what is in the build directory.

[DustinGrau-PSC]

Ah, that makes sense now. I've been able to get a successful run from JsonDocumentation and it appears to produce all the basic information I would expect in the JSON output, though it doesn't seem to include any comments from the code. The format we use is what also works for the other documentation methods, and appears to match what was suggested in the documentation for the task. Is this still under development?

[spazzymoto]

Is there a usable example which shows how the JsonDoc should be used and how to consume the results?

Documentation: https://wiki.rssw.eu/pct/JsonDocumentation.md No example on how to consume the result. @spazzymoto Did you push the updated ABLDuck code somewhere ?

I only have it locally at the moment it still requires some work unfortunately.

[gquerret]

I've been able to get a successful run from JsonDocumentation and it appears to produce all the basic information I would expect in the JSON output, though it doesn't seem to include any comments from the code.

Use a development build: https://ci.rssw.eu/job/PCT/job/master/ And the build.xml from this ADE repo: https://github.com/Riverside-Software/cuddly-octo-ade

[DustinGrau-PSC]

Thank you! That build.xml is exactly what I was originally looking for, and still taught me a few things I didn't know before. The development build is certainly an improvement--I'm getting more comments in the generated results, and I'm also now aware that these appear in their own "comments" array which I previously missed.