docs: Refactor, enhance and uniformize ogsf docstrings #6130
+572
−400
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…oxygen rendering and also correct parsing inside IDEs. Adding `@brief` makes that text visible in the summary table place near the begining, instead of only below in the docs for that field. Only using `/** foo bar */` shows up in the docs for that field below, but not near the begining.
echoix
changed the title
echoix
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
All of this started by my wanting to know what the "color value" int was, and if the color of gvstyle was referring to the same concept. So I dug a bit, and ended up making the information available rendered in doxygen, or injected new knowledge into the docstrings.
First, there's the file lib/ogsf/gsdrape.c and lib/ogsf/gs_util.c that I went and interpreted the code to add the parameter directions
[in],[out], or[in,out]. Since it was like a sudoku, the related functions had to be annotated too, when known, in order to fill out more.For lib/ogsf/gs_util.c, I also interpreted the code to indicate if the arrays were for 2D vectors or 3D vectors.
For lib/ogsf/gsd_objs.c, the main part of the work of this PR, I completely refactored the docs, making them uniform. I started out with AI to rewrite one single docstring, then completly overhauled it by the end when adapting it for each of the functions. I also asked Copilot for the docs of one function that wasn't documented and hard to understand, then I rewrote 80%+ of it to tune and enhance it. I was surprised by how close it got.
Finally, for include/grass/ogsf.h, I formatted the docstrings of the typedef's fields so that they:
That third goal is why, after many trials and errors, opted for using
/** @brief bla bla bla */above the member to document, more standard and used by other tools, rather than a doxygen-specific advanced syntax that would allow attaching a documentation comment to a code preceding it, rather than following it. Being able to hover around when coding is almost as important and useful to me, as firing up the developper's documentation online to find the same info.Lots of screenshots!
For example:
Before:
After:
Before:
After:
Before & after:
