FreeOrion

Forums for the FreeOrion project
It is currently Mon Dec 11, 2017 2:11 am

All times are UTC




Post new topic Reply to topic  [ 3 posts ] 
Author Message
PostPosted: Mon Sep 12, 2016 7:31 am 
Offline
Programmer

Joined: Sun Feb 14, 2016 12:08 am
Posts: 358
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 321 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 321 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.


Top
 Profile  
 
PostPosted: Mon Sep 12, 2016 12:50 pm 
Offline
Programmer
User avatar

Joined: Fri Mar 01, 2013 9:52 am
Posts: 1040
Location: Germany
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


Top
 Profile  
 
PostPosted: Mon Sep 12, 2016 2:47 pm 
Offline
Programmer

Joined: Sun Feb 14, 2016 12:08 am
Posts: 358
.O7 PR #967


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 3 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB® Forum Software © phpBB Group