amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-10-03 13:10:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Use one-line module docstrings in the API checker scripts

Browse Source 
Codacy runs two docstring checkers with opposite rules for module
docstrings: with the summary on the first line it reported D213, with
the summary on the second line it reports D212. A one-line docstring
satisfies both. Keep the summary as the docstring and move the details
into a comment below it; nothing reads the module docstrings.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
2026-09-28 18:42:34 +02:00
parent da5097abcd
commit 4c73319d3b
5 changed files with 57 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/api_checker/extract_api.py
+17 -19
View File
@@ -1,24 +1,22 @@
#!/usr/bin/env python3
"""
Extract the public API surface of nlohmann/json using libclang AST.
"""Extract the public API surface of nlohmann/json using libclang AST."""
This tool derives the public API from C++ semantics (class templates, access specifiers,
namespace scoping) independently of documentation status. The extracted surface is the
source of truth for what is considered "public API" — doc-checking and API diffing are
downstream consumers of this snapshot.
Strategy:
1. Parse include/nlohmann/json.hpp with libclang (with proper system includes)
2. Walk the primary class-template definitions of the 6 known public classes
3. Extract callable members (methods, constructors, destructors, conversion ops) and type aliases
4. Extract free functions/operators in nlohmann:: (excluding detail::)
5. Handle alias-exposed exception types by following the alias to the detail:: definition
6. Normalize away the ABI inline-namespace (json_abi_v3_12_0, json_abi_diag_v3_12_0, etc.)
7. Emit a snapshot with an overload-disambiguating identity key and documentation status
Output includes both public_api (all tracked public entities) and documented_non_public
(entities with @sa comments that are NOT in the public surface — used for validation).
"""
# This tool derives the public API from C++ semantics (class templates, access specifiers,
# namespace scoping) independently of documentation status. The extracted surface is the
# source of truth for what is considered "public API" — doc-checking and API diffing are
# downstream consumers of this snapshot.
#
# Strategy:
# 1. Parse include/nlohmann/json.hpp with libclang (with proper system includes)
# 2. Walk the primary class-template definitions of the 6 known public classes
# 3. Extract callable members (methods, constructors, destructors, conversion ops) and type aliases
# 4. Extract free functions/operators in nlohmann:: (excluding detail::)
# 5. Handle alias-exposed exception types by following the alias to the detail:: definition
# 6. Normalize away the ABI inline-namespace (json_abi_v3_12_0, json_abi_diag_v3_12_0, etc.)
# 7. Emit a snapshot with an overload-disambiguating identity key and documentation status
#
# Output includes both public_api (all tracked public entities) and documented_non_public
# (entities with @sa comments that are NOT in the public surface — used for validation).
import argparse
import json