Docs: add coding conventions doc and improve Doxygen infrastructure#254
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Capture the naming/extension/header-guard/LP-state decisions from recent refactoring work in an enforceable, discoverable doc/dev/conventions.md, and link it from the README Contributing section. Formatting rules are left to .clang-format as the machine-checkable source of truth.
Replace the stale, un-wired doc/Doxyfile (committed in a85b983; EXTRACT_ALL=YES and OUTPUT_DIRECTORY=doc, which would dump HTML into the source tree) with a CMake-wired, on-demand docs build: - doc/CMakeLists.txt uses the modern doxygen_add_docs() (CMake >=3.9) instead of copying ROSS's older configure_file + add_custom_command form. Output goes to the build tree (${CMAKE_BINARY_DIR}/doc); INPUT is codes/ + src/ with the README as the mainpage. - EXTRACT_ALL=NO + WARN_IF_UNDOCUMENTED=NO are the key settings: the output contains only entities that carry a /** */ comment, so it starts near-empty and fills in as docs are added (YAML config first) with no warning spam about the undocumented legacy tree. - option(CODES_BUILD_DOXYGEN ... OFF); add_subdirectory(doc) only when ON, so the common build is unaffected and `docs` is never part of `all`. No CI gate. - conventions.md gains a Documentation-comments subsection: doc-as-you-go / no mass backfill, how to build the docs, output lives in the gitignored build tree, and the @file-block requirement for free C functions to render.
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.
Stands up two developer-doc deliverables, in separate commits:
doc/dev/conventions.md): one place for the rules thatclang-formatcan't enforce: snake_case naming,.cxx/.c/.hextensions,CODES_/SRC_..._Hheader guards (not#pragma once), etc.doc/Doxyfile(which dumped HTML into the source tree) with a CMake-wired, on-demanddocstarget viadoxygen_add_docs(). Opt-in behind-DCODES_BUILD_DOXYGEN=ON(OFF by default). Output goes to the build tree. As I work on refactoring, I will improve doxygen comments on things I touch so the docs will improve over time. Code reviewers should also ensure that any PRs they review have appropriate documentation added.Right now the docs are just available locally, but in the future I plan to make them available online, perhaps on read the docs.
To build locally: