Skip to content

Add developer documentation for managers in NEST #3465

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 35 commits into
base: master
Choose a base branch
from

Conversation

jessica-mitchell
Copy link
Contributor

@jessica-mitchell jessica-mitchell commented Apr 10, 2025

This PR creates pages dedicated to explaining how managers work in NEST.
The goal is to provide newer developers with an overview.

Currently a general overview is given in developer_space/managers/index.html
And each manager has its own page with a brief description and generated docs from doxygen output (extracting the C++ comments) using the extension breathe. Additional details are provided for MUSICManager and SPManager, after discussion with @alpinangu on what would be useful to include. If the review of these pages is positive than we can include such details in each manager page.

The analysis of code and text descriptions was aided by AI.

@jessica-mitchell jessica-mitchell added T: Enhancement New functionality, model or documentation S: Normal Handle this with default priority I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) labels Apr 10, 2025
@github-project-automation github-project-automation bot moved this to In progress in Documentation Apr 10, 2025
Copy link

@alpinangu alpinangu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Jessica, I think the changes you made are really helpful.

I really like the Relationships with Other Managers section. I think it’s super useful for someone who doesn’t have a clear big-picture understanding. This section provides that well from the manager’s point of view. I also like that there are links to the listed managers.

I also really like the detailed operation sequence. The explanations are clear and well-ordered, and I appreciate how it includes the code too—so you can look at the function without needing to switch tabs. Maybe it could also mention which parts of the source code call these functions, if it’s not too hard to trace.

I also really liked how MUSICManager has a section for MPI, since both it and MUSIC rely heavily on it.

The Overview section and the description at the top also provide a nice explanation. It’s helpful for people who just want a quick reminder instead of going through the detailed breakdowns.

It might be helpful to include a super brief description of what the class members are for. Personally, when I start working on a class, I like to understand the members before diving into the functions.

Lastly, I found that some of the Doxygen descriptions could be more detailed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) S: Normal Handle this with default priority T: Enhancement New functionality, model or documentation
Projects
Status: In progress
Development

Successfully merging this pull request may close these issues.

2 participants