Documenting content definition tags

Programmers discuss here anything related to FreeOrion programming. Primarily for the developers to discuss.

Moderator: Committer

Post Reply
Message
Author
dbenage-cx
Programmer
Posts: 389
Joined: Sun Feb 14, 2016 12:08 am

Documenting content definition tags

#1 Post by dbenage-cx » Mon Sep 12, 2016 7:31 am

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.
docu_tags_all.png
Main All Tags page
docu_tags_all.png (122.51 KiB) Viewed 566 times
Not certain why CTRL_EXTINCT links twice, when CTRL_ALWAYS_REPORT does not.
docu_tags_local.png
Definition point
docu_tags_local.png (64.66 KiB) Viewed 566 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)?
Any content posted should be considered licensed GNU GPL 2.0 and/or CC-BY-SA 3.0 as appropriate.

User avatar
adrian_broher
Programmer
Posts: 1072
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: Documenting content definition tags

#2 Post by adrian_broher » Mon Sep 12, 2016 12:50 pm

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.
Resident code gremlin
Attached patches are released under GPL 2.0 or later.
Git author: Marcel Metz

dbenage-cx
Programmer
Posts: 389
Joined: Sun Feb 14, 2016 12:08 am

Re: Documenting content definiion tags

#3 Post by dbenage-cx » Mon Sep 12, 2016 2:47 pm

.O7 PR #967

Post Reply