About JsonDocumentation

[NerdFan]

Just wondering about JsonDocumentation that according release notes: "will replace the other documentation task in next release".
What is idea behind? Where to consume outcome?

[gquerret]

Multiple goals:

• From a technical perspective, the existing documentation relies on the parser provided by Progress. As Riverside maintains its own parser for its code analysis product, cutting the dependency on a library we have no control over is a good move. There are also missing functionalities in the Progress that are available in our parser
• Also from a technical perspective, this task relies on the rcode to read the method signatures (thus with all symbols resolved, such as .Net assemblies). Doc is more accurate, and execution is much faster, as the parser only has to attach the right documentation to each method.
• Works on Linux and Windows
• There's currently no task to transform the Json output to HTML ; the developers of ABLDuck and HtmlDocumentation already said they would work on migrating their tasks to consume Json, but I think they ran out of time. Probably worth to ping them again :-)
• Both the SonarQube rules and the upcoming VSCode plugin will depend on the documentation output, in order to flag deprecated methods for example, or display documentation when hovering method calls. That probably won't directly use the Json output (in favor of some internal format), but the way documentation is generated will be common

So it might be a bit early if you want to switch to JsonDocumentation, as it can't generate Html ouput. But if you're ready to spend a bit of time, I think it's easy to adapt the ABLDuck task to use this output. PR are always welcome !

[gquerret]

Could you upload this sample documentation somewhere ? That would be helpful to have overall comments.

[DustinGrau-PSC]

Would the eventual intent of this combination of ABLDuck + JsonDocumentation be that the UI stands on it's own and you simply update a central JSON file with new documentation metadata? Would there be any timeframe or beta versions available to test this arrangement?

[spazzymoto]

Hey guys,
Sorry for the massive delay, between work and studying I haven't been able to find much time to work on this.

I spent some time this weekend to get it to a better state where I can start finishing it.

There is still a lot missing that i hope to add over the next few days.

@DustinGrau-PSC that is correct you would run JsonDocumentation to generate the data.json file and then just copy it to a location that is serving the ABLDuck webpage.

There will still be an ABLDuck task that will extract the version of ABLDuck compatible with the JSONDocument output and to allow you to config some custom code tags and such.

https://spazzymoto.github.io/ablduck-next-example

[gquerret]

Looks nice ! Please keep us updated :-)

[spazzymoto]

Updates:

Updated the file icons

Most of the work went into the comment tags system to deal with @author @deprecated @internal etc. Now you will be able to define your own tags using something like the following

const CUSTOM_TAGS = { 'revision': { type: 'key_value', regex: new RegExp('^@revision\\s+(?<key>[\\d\\.]+)\\s+(?<value>.*)$', 's'), color: '#17802f', templates: { sidebar: 'Revision [key]', comment: '[key] -> [value].' } }, 'internal': { type: 'tag', color: '#600', templates: { menu: 'Int', signature: 'Internal', sidebar: 'Internal Only', comment: 'NOTE:This is an internal [parent] for use by the framework. Don\'t rely on its existence.' } }, }

On the following comment

Will display as follows

I will expose this in a nice way in the ABLDuck task. The templates allow you to specify what to show in what location

• comment : this is shown above the code comments
• sidebar : this shows in the sidebar that floats to the right of the comment
• menu: shows a tag in the menu
• signature: shows a tag next to the signature

Supported tags types will be

• key_value : @tag key value where key and value are named groups in your regex
• value : @tag value where value is a named group in your regex
• tag : doesnt support a regex, it is just the @tag

Worked on the filtering widget too, this should work now.

Take it for a test and let me know what you think. The Utilities & Builder class have members that have been filtered out so be sure to enable deprecate, internal and inherited for example.

https://spazzymoto.github.io/ablduck-next-example

[gquerret]

@spazzymoto I assume that this works with any Json documentation, right ? Could you publish the website for those two files ?

• https://dl.rssw.eu/corelib.json
• https://dl.rssw.eu/netlib.json

[spazzymoto]

Sure thing

• https://spazzymoto.github.io/corelib/
• https://spazzymoto.github.io/netlib/

Those have shown me a lot of places I need to work on thanks. I think I will make the base font size a bit smaller to give a bit more real estate.

Then for the long signatures I need to think, probably drop the modifier if its INPUT. This is why i think i removed the datatype in the previous version

[spazzymoto]

@gquerret is there any progress on the procedure part of the documentation task?

[spazzymoto]

Added some search functionality, once again refresh cache to get latest changes

[spazzymoto]

The custom links to other documentation is done.

You can configure regexes to interrogate the datatype

Then these will be linked in the documentation

[clement-brodu]

Hello,

That sounds great!
When do you think you'll be able to publish a first version on github?
May be we could help ?

[clement-brodu]

Up,

@spazzymoto, do you have any news about this ?

We are looking forward to use it !

[spazzymoto]

Hey @clement-brodu,

There was/is some information missing from the JsonDocumentation task the last time I checked that I needed to finish off the UI.

I will see if I can put some time aside to look at implementing it.

[clement-brodu]

Feel free to ask if you need help to deal with those last issues 🙂

[clement-brodu]

Any Updates @spazzymoto ?

[spazzymoto]

Hi @clement-brodu,

Apologies work has been busy. I have 2 weeks of leave starting today, I will try dust off the project and get it committed to the abl duck repo so you can help ironing out the last few things that need to be done.