Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Document content definition tags #967
From forum thread
Specific tags are currently undocumented, leaving those trying to reference them to hunt for the current intended use.
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).
Also added default/python to the documented files, with a filter to only document python files with a tag entry.
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)?
changed the title from
[WIP][Feedback] Document content definition tags
Document content definition tags
Sep 12, 2016
status:work in progress
Sep 12, 2016
Looks good in general.
Is there a particular reason why you add sections to the tags? I don't see much value into separating 'core' and 'mod' tags.
You're talking about the duplicated entries, right?
It's not like I will fight for keeping CREATE_SUBDIRS set to YES if it's causing bugs, I just liked the doc root directory to be clean as possible. But it seems like the xrefitem keyword doesn't work well with CREATE_SUBDIRS, at least there are some bugs in the doxygen bugtracker that go in that direction.
I was imagining content creators documenting a custom resource directory. That seems like a long term prospect, so agree it should lose the separation.
The duplicated entry is a minor annoyance imo, there may not be a viable solution to it.
I initially envisioned, and was trying for:
And then at the definition point:
SOME_TAG_1 brief description
The duplication occurs for any additional use within the same scope.
Comments in python are apparently not parsed for this alias if the comment is indented. Adjusted filter to strip the spacing for these, so as not to break pep8 adherence.
Would a rebranch with reduced commits be preferred?
You can rebase within this branch.
I'm happy with the outcome. The only criticism I have is that the implementation of
would do the same as yours with half of the code to maintain.
Thank you for reviewing and assist.
I originally went this route (and commenting out lines instead of no output), but without context in the file, doxygen ignored the tag.
But that's still no reason to read the file twice.
Sorry if I'm being dense, won't this output all given files?
Could fill up a buffer and only print if a match was found.