Open
Conversation
@defgroup names a 'module' not a group of related methods. @name is used to group documentation for a related group of methods in a class.
|
jgallagher59701
requested review from
hannahilea and
ndp-opendap
and removed request for
ndp-opendap
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary: There was no ticket for this. I was using it as a real example of a more structured approach to using codex (from OpenAI) for development. To see what I mean by 'more structured' look at AGENTS.md. That file is used a part of context for prompt sent to the LLM. Similarly, look at Doxygen-plan.md to see how I built up the new doxygen comments using codex.
The long version:
My process for this was to ask the LLM to build a plan to update some of the method documentation comments. I said this:
Look at the classes at the top-level in the repo and directories http_dap, d4_ce, d4_function and geo and tell me how many public methods lack documentation. ignore code in the gl, tests and unit-tests directories.It responded 1,918, plus a bunch of other stuff.
I got codex to build a plan using this:
Devise a plan for writing the documentation for the 1,918 public methods. This plan should break the task into parts such that groups of related methods are documented in stages when the changes made and reviewed by me before starting work on the next stage. Use the existing setting in the repo's docy.conf file. Output the plan as a markdown document that can be used as a prompt in the future.The result was close, but not what I wanted.
Save this plan as Doxygen-plan.md to the repo.I asked some questions about this and modified the markdown in a few places. Unfortunately, there's no record of those changes.
Then I started a new 'chat' (so there was no context cary-over) and used:
Implement Stage 1 of Doxygen planOff it went. After each stage it responded with a bit about what it had done and I reviewed the edits, fixed ones that needed fixing, and committed them. Using
Approvedas a prompt moved onto the next 'stage' in the plan.
Once all that was done, I found a few things about the doc page that looked kind of tired, so I spent about 2 hours fixing that stuff up (getting the build date on the 'main page', fixing my broken use of @defgroup - grrr, getting make to rebuild doxy.conf when doxy.conf.in changes, ...). The 9 stages of doxygen comment writing took about 35 minutes.