mirror of
https://github.com/nlohmann/json.git
synced 2026-08-28 20:07:32 +00:00
Add AST-based public API checker and fix documentation gaps it found (#3691)
Adds tools/api_checker/: extract_api.py derives the public API surface directly from the libclang AST (independent of documentation status), check_docs.py flags public entries missing @sa links (and @sa on non-public ones), diff_api.py does an overload-aware breaking/feature diff between two refs, check_macros.py cross- checks documented macros against #define sites, and snapshot_release.py backfills immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0 through v3.12.0) so diff_api.py can compare releases without live extraction. POLICY.md documents what counts as public API and what stability is guaranteed. Running this tooling against the current tree found and fixed a real documentation backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/ operator=, byte_container_with_subtype's comparison operators, several orphaned type aliases), each with a compiled and output-verified example, plus missing @sa comments and stale/incorrect Version History entries on several existing pages (found by diffing consecutive release pairs and checking whether the resulting change was actually reflected in the target page's history section). Also adds docs/home/api_changes.md, a per-release, per-function reference of public API changes (v3.1.0 through v3.12.0) generated from the history/ snapshots, complementing (not replacing) the existing release notes. Along the way, found and fixed several extractor bugs by testing against real release tags rather than trusting the algorithm in isolation -- most notably an identity-key scheme based on libclang's USR that encoded the enclosing class template's own arity, and a since-renamed ABI inline-namespace pattern (json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex attempts stripped correctly. Both are documented in extract_api.py's docstrings and tools/api_checker/history/README.md so the failure mode doesn't recur silently. .github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI, advisory-only for now (documented backlog may not be at zero for entities this PR didn't touch), plus a blocking drift check on the committed tools/api_checker/api_surface.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
6ba332c7df
commit
f23b3c63a2
@@ -31,15 +31,21 @@ input.
|
||||
template<typename BasicJsonType>
|
||||
struct json_sax
|
||||
{
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/number_integer_t/
|
||||
using number_integer_t = typename BasicJsonType::number_integer_t;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/number_unsigned_t/
|
||||
using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/number_float_t/
|
||||
using number_float_t = typename BasicJsonType::number_float_t;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/string_t/
|
||||
using string_t = typename BasicJsonType::string_t;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/binary_t/
|
||||
using binary_t = typename BasicJsonType::binary_t;
|
||||
|
||||
/*!
|
||||
@brief a null value was read
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/null/
|
||||
*/
|
||||
virtual bool null() = 0;
|
||||
|
||||
@@ -47,6 +53,7 @@ struct json_sax
|
||||
@brief a boolean value was read
|
||||
@param[in] val boolean value
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/boolean/
|
||||
*/
|
||||
virtual bool boolean(bool val) = 0;
|
||||
|
||||
@@ -54,6 +61,7 @@ struct json_sax
|
||||
@brief an integer number was read
|
||||
@param[in] val integer value
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/number_integer/
|
||||
*/
|
||||
virtual bool number_integer(number_integer_t val) = 0;
|
||||
|
||||
@@ -61,6 +69,7 @@ struct json_sax
|
||||
@brief an unsigned integer number was read
|
||||
@param[in] val unsigned integer value
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/number_unsigned/
|
||||
*/
|
||||
virtual bool number_unsigned(number_unsigned_t val) = 0;
|
||||
|
||||
@@ -69,6 +78,7 @@ struct json_sax
|
||||
@param[in] val floating-point value
|
||||
@param[in] s raw token value
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/number_float/
|
||||
*/
|
||||
virtual bool number_float(number_float_t val, const string_t& s) = 0;
|
||||
|
||||
@@ -77,6 +87,7 @@ struct json_sax
|
||||
@param[in] val string value
|
||||
@return whether parsing should proceed
|
||||
@note It is safe to move the passed string value.
|
||||
@sa https://json.nlohmann.me/api/json_sax/string/
|
||||
*/
|
||||
virtual bool string(string_t& val) = 0;
|
||||
|
||||
@@ -85,6 +96,7 @@ struct json_sax
|
||||
@param[in] val binary value
|
||||
@return whether parsing should proceed
|
||||
@note It is safe to move the passed binary value.
|
||||
@sa https://json.nlohmann.me/api/json_sax/binary/
|
||||
*/
|
||||
virtual bool binary(binary_t& val) = 0;
|
||||
|
||||
@@ -93,6 +105,7 @@ struct json_sax
|
||||
@param[in] elements number of object elements or -1 if unknown
|
||||
@return whether parsing should proceed
|
||||
@note binary formats may report the number of elements
|
||||
@sa https://json.nlohmann.me/api/json_sax/start_object/
|
||||
*/
|
||||
virtual bool start_object(std::size_t elements) = 0;
|
||||
|
||||
@@ -101,12 +114,14 @@ struct json_sax
|
||||
@param[in] val object key
|
||||
@return whether parsing should proceed
|
||||
@note It is safe to move the passed string.
|
||||
@sa https://json.nlohmann.me/api/json_sax/key/
|
||||
*/
|
||||
virtual bool key(string_t& val) = 0;
|
||||
|
||||
/*!
|
||||
@brief the end of an object was read
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/end_object/
|
||||
*/
|
||||
virtual bool end_object() = 0;
|
||||
|
||||
@@ -115,12 +130,14 @@ struct json_sax
|
||||
@param[in] elements number of array elements or -1 if unknown
|
||||
@return whether parsing should proceed
|
||||
@note binary formats may report the number of elements
|
||||
@sa https://json.nlohmann.me/api/json_sax/start_array/
|
||||
*/
|
||||
virtual bool start_array(std::size_t elements) = 0;
|
||||
|
||||
/*!
|
||||
@brief the end of an array was read
|
||||
@return whether parsing should proceed
|
||||
@sa https://json.nlohmann.me/api/json_sax/end_array/
|
||||
*/
|
||||
virtual bool end_array() = 0;
|
||||
|
||||
@@ -130,16 +147,23 @@ struct json_sax
|
||||
@param[in] last_token the last read token
|
||||
@param[in] ex an exception object describing the error
|
||||
@return whether parsing should proceed (must return false)
|
||||
@sa https://json.nlohmann.me/api/json_sax/parse_error/
|
||||
*/
|
||||
virtual bool parse_error(std::size_t position,
|
||||
const std::string& last_token,
|
||||
const detail::exception& ex) = 0;
|
||||
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/json_sax/
|
||||
json_sax() = default;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/json_sax/
|
||||
json_sax(const json_sax&) = default;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/json_sax/
|
||||
json_sax(json_sax&&) noexcept = default;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/operator=/
|
||||
json_sax& operator=(const json_sax&) = default;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/operator=/
|
||||
json_sax& operator=(json_sax&&) noexcept = default;
|
||||
/// @sa https://json.nlohmann.me/api/json_sax/~json_sax/
|
||||
virtual ~json_sax() = default;
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user