Page 1 of 1

Documenting content definition tags

Posted: Mon Sep 12, 2016 7:31 am
by dbenage-cx
Specific tags are currently undocumented, leaving those trying to reference them to hunt for the current intended use.
Some method to address documenting these would likely help even the more experienced members.

Anyone focusing on a specific section (e.g. AI) will likely want a reference to tags in each of the others.
Maintaining a central file (or 4 files for compiled / definition content / python content / AI) seems a burden, so I tried implementing with doxygen.
Since doxygen is not really designed to document the values of sparsely placed variables, the output is not exactly as I'd hope, though it is functional.

A key change here is setting CREATE_SUBDIRS = NO which results in a different file output and layout. Restoring to YES results in a broken link at the definition point ("Definition Tag" -> tag group page), at least in my locally generated version (doxygen v1.8.11). If changing is not acceptable, the list will still generate and link to the references correctly, the user will just need to use the menu for a list.

Also added default/python to the documented files, with a filter to only document python files with a tag entry.
Main All Tags page
Main All Tags page
docu_tags_all.png (122.51 KiB) Viewed 1464 times
Not certain why CTRL_EXTINCT links twice, when CTRL_ALWAYS_REPORT does not.
Definition point
Definition point
docu_tags_local.png (64.66 KiB) Viewed 1464 times
Documenting tags within the FOCS definitions will probably require writing some rule to parse them (if moving to python goes well, then not an issue).

Are there any alternate ideas roaming around (or pointers for those with a better handle on doxygen)?

Re: Documenting content definition tags

Posted: Mon Sep 12, 2016 12:50 pm
by adrian_broher
The idea doesn't sound too wrong.

Can you copy the whole OP into a github PR? I have the general feeling that concrete implementation discussions get lost in the forum, especially if you have a pull request at hand.

Re: Documenting content definiion tags

Posted: Mon Sep 12, 2016 2:47 pm
by dbenage-cx
.O7 PR #967