Skip to content
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

Update the public packages' documentation #119

Merged
merged 3 commits into from
Oct 9, 2023

Conversation

pniedzielski
Copy link
Collaborator

Issue number of the reported bug or feature request: Part of #118

Describe your changes
As part of the work on making sure our documentation can build correctly with just doxygen, these three patches bring our public package documentation up-to-date with the current state of our API, and remove old, out-of-date documentation that mostly duplicates this.

Testing performed
Applying these patches and building with doxygen yields package documentation that contains all components in each package, as well as their purpose.

Additional context
This PR will be part of a series of PRs to tackle #118, as that work is rather large, and these patches are independent of the other work, and independently useful for an open source contributor reading the code.

Our three public API packages—`bmqa`, `bmqpi`, and `bmqt`—were given
Markdown `README` files that replicate the BDE-style `doc/*.txt`
files, excluding some aspects of their component hierarchy.  However,
these `README` files have not been updated to include recent changes
to the API, such as the addition of subscription support.  This patch
adds the missing components to each of these `README` files, bringing
them up to date with the current public API.

Applying this patch will enable us to build our API documentation
directly from the Doxygen comments, rather than using the `bdedox`
tool that our API documentation is currently built with.

Signed-off-by: Patrick M. Niedzielski <[email protected]>
This patch removes the public BDE-style package documentation for our
three public packages: `bmqa`, `bmqpi`, and `bmqt`.  This
documentation is old and incomplete, and a more update-to-date version
can be found already in the `README.md` for each of these packages.
These `README.md` files can be used directly by Doxygen as well,
rather than the Doxygen component documentation being generated as a
separate step from the BDE-style documentation.

Signed-off-by: Patrick M. Niedzielski <[email protected]>
This patch updates the BDE-style component membership list for `bmqa`.
This change is trivial to do, and this package is the only one whose
membership list was out-of-date, so we do this rather than wholesale
remove BDE-style membership lists.

Signed-off-by: Patrick M. Niedzielski <[email protected]>
@pniedzielski pniedzielski added documentation Improvements or additions to documentation A-Docs Area: Documentation labels Sep 26, 2023
@pniedzielski pniedzielski requested a review from a team as a code owner September 26, 2023 21:16
Copy link
Collaborator

@678098 678098 left a comment

Choose a reason for hiding this comment

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

LGTM!

@pniedzielski pniedzielski merged commit 1f3cf70 into bloomberg:main Oct 9, 2023
8 checks passed
@pniedzielski pniedzielski deleted the doxygen/readmes branch October 30, 2024 18:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Docs Area: Documentation documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants