FreeOrion
http://www.freeorion.org/forum/

Documenting content definition tags
http://www.freeorion.org/forum/viewtopic.php?f=9&t=10221
Page 1 of 1

Author:  dbenage-cx [ Mon Sep 12, 2016 7:31 am ]
Post subject:  Documenting content definition tags

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.

Attachment:
File comment: Main All Tags page
docu_tags_all.png
docu_tags_all.png [ 122.51 KiB | Viewed 540 times ]

Not certain why CTRL_EXTINCT links twice, when CTRL_ALWAYS_REPORT does not.

Attachment:
File comment: Definition point
docu_tags_local.png
docu_tags_local.png [ 64.66 KiB | Viewed 540 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)?

Author:  adrian_broher [ Mon Sep 12, 2016 12:50 pm ]
Post subject:  Re: Documenting content definition tags

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.

Author:  dbenage-cx [ Mon Sep 12, 2016 2:47 pm ]
Post subject:  Re: Documenting content definiion tags

.O7 PR #967

Page 1 of 1 All times are UTC
Powered by phpBB® Forum Software © phpBB Group
https://www.phpbb.com/