From 90164325fb787cb1f2c70e1e5442fe0ff1ac8d25 Mon Sep 17 00:00:00 2001 From: Dmitry Arkhipov Date: Mon, 15 Jul 2024 17:59:28 +0300 Subject: [PATCH 1/2] flattened docs for function overloads --- doc/Jamfile | 1 + doc/reference.jinja | 351 +++++++++++++++++++++++++++++++++++ include/boost/json/parse.hpp | 151 ++++----------- 3 files changed, 383 insertions(+), 120 deletions(-) create mode 100644 doc/reference.jinja diff --git a/doc/Jamfile b/doc/Jamfile index 5b9399de0..a478b335e 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -38,6 +38,7 @@ docca.pyreference reference.qbk STRIP_FROM_PATH=$(include-prefix) config.json + reference.jinja ; #------------------------------------------------------------------------------- diff --git a/doc/reference.jinja b/doc/reference.jinja new file mode 100644 index 000000000..c5e0ce24a --- /dev/null +++ b/doc/reference.jinja @@ -0,0 +1,351 @@ +{% import "docca/quickbook/components.jinja2" as comps -%} + +{% macro write_namespace(entity) -%} + {%- for m in entity.members.values() | select("Type") | sort -%} + {{ write_type(m) }} + {%- endfor -%} + + {%- for m in entity.members.values() | select("OverloadSet") | sort -%} + {{ write_overload_set(m) }} + {%- endfor -%} + + {%- for m in entity.members.values() | select("Variable") | sort -%} + {{ comps.write_variable(m) }} + {%- endfor -%} +{%- endmacro %} + +{% macro write_type(entity) %} +{% call(segment) comps.section(entity) %} + +{%- if segment == "summary" -%} +{%- if entity is Scope -%} +{#- public members -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Type") + | selectattr("access", "eq", Access.public), + 'Types') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.nonstatic), + 'Member Functions') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.static), + 'Static Member Functions') }} {#- -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.public) + | rejectattr("is_static"), + 'Data Members') }} {#- -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.public) + | selectattr("is_static") + | reject("in", entity.objects), + 'Static Members') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.friend), + 'Friends') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.free), + 'Related Non-member Functions') }} {#- -#} +{#- protected members -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Type") + | selectattr("access", "eq", Access.protected), + 'Protected Types') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.protected) + | selectattr("kind", "eq", FunctionKind.nonstatic), + 'Protected Member Functions') }} {#- -#} +{{ comps.function_summary_table( + entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.protected) + | selectattr("kind", "eq", FunctionKind.static), + 'Protected Static Member Functions') }} {#- -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.protected) + | rejectattr("is_static"), + 'Protected Data Members') }} {#- -#} +{{ comps.simple_summary_table( + entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.protected) + | selectattr("is_static") + | reject("in", entity.objects), + 'Protected Static Members') }} {#- -#} +{%- endif -%} + +{% if entity is Enum -%} +{%- call(member) comps.summary_table(entity.objects, "Values") -%} + [[^{{ comps.escape(member.name) }}] + ] + [{{ comps.description(member.brief) | trim }} + ] +{%- endcall -%} +{%- else -%} +{{ comps.simple_summary_table(entity.objects, 'Values') }} +{%- endif -%} +{%- endif -%} + +{%- if segment == "members" -%} +{%- if entity is Scope -%} +{#- public member subsections -#} +{% for member in entity.members.values() + | select("Type") + | selectattr("access", "eq", Access.public) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.nonstatic) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.static) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.public) + | rejectattr("is_static") -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.public) + | selectattr("is_static") + | reject("in", entity.objects) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.friend) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.public) + | selectattr("kind", "eq", FunctionKind.free) -%} +{{ write_entity(member) }} +{% endfor %} +{#- protected member subsections -#} +{%- for member in entity.members.values() + | select("Type") + | selectattr("access", "eq", Access.protected) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.protected) + | selectattr("kind", "eq", FunctionKind.nonstatic) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("OverloadSet") + | selectattr("access", "eq", Access.protected) + | selectattr("kind", "eq", FunctionKind.static) -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.protected) + | rejectattr("is_static") -%} +{{ write_entity(member) }} +{% endfor %} +{%- for member in entity.members.values() + | select("Variable") + | selectattr("access", "eq", Access.protected) + | selectattr("is_static") + | reject("in", entity.objects) -%} +{{ write_entity(member) }} +{% endfor %} +{%- endif -%} + +{% if entity is not Enum -%} +{%- for object in entity.objects -%} +{{ write_entity(object) }} +{% endfor %} +{%- endif -%} +{%- endif -%} + +{% endcall %} +{% endmacro %} + +{% macro write_entity(entity) -%} + {% if entity.access != Access.private or Config.include_private -%} + {%- if entity is Namespace -%} + {{ write_namespace(entity) }} + {%- elif entity is Type -%} + {{ write_type(entity) }} + {%- elif entity is OverloadSet -%} + {{ write_overload_set(entity) }} + {%- elif entity is Variable -%} + {{ comps.write_variable(entity) }} + {%- elif entity is Function -%} + {{ comps.write_function(entity) }} + {%- endif -%} + {%- endif -%} +{%- endmacro %} + +{% macro write_overload_set(oset) -%} +{%- if (oset | length) == 1 -%} +{%- else %} +{%- endif -%} + +[section:{{ comps.anchor(oset) }} {{ comps.abridged_fqn(oset) }}] +{% if oset.scope is Namespace -%} + [indexterm1 {{ comps.escape(oset.name) }}] +{% else -%} + [indexterm2 {{ comps.escape(oset.name) }}..{{ comps.escape(oset.scope.name) }}] +{% endif %} + +{{ comps.description(oset[0].brief) }} + +{% if oset.location + and (oset.scope is Namespace or oset.is_friend) -%} + Defined in header {{ comps.source_header(oset.location.file) }} +{%- endif %} + +{{ comps.heading('Synopsis') }} +``` +{% for func in oset -%} +{{ comps.function_declaration(func) }} +{%- if not (loop.first and loop.last) %} // ({{ loop.index }}) {% endif %} + +{% endfor -%} +``` + +{% if oset[0].description -%} +{% if oset[0].description[0] is not Section -%} + {{ comps.heading('Description') }} +{%- endif %} +{{ oset_description(oset) }} +{%- endif %} + +{% if Config.get('convenience_header') + and oset.location + and (oset.scope is Namespace + or (oset.kind in (FunctionKind.free, FunctionKind.friend))) -%} +Convenience header {{ comps.source_header(Config.convenience_header) }} +{%- endif %} + +[endsect] +{% endmacro %} + +{% macro oset_description(oset, nesting='') -%} +{%- for part in oset[0].description -%} + +{%- if part is Paragraph -%} +{{ comps.phrase(part) }} + +{% elif part is List -%} +{{ comps.itemised(part, nesting) }} +{%- elif part is Section -%} +{{ comps.subsection(part) }} +{%- elif part is CodeBlock %} +{{ nesting }}``` +{% for line in part -%} +{{nesting}}{{line}} +{% endfor -%} +{{ nesting }}``` +{% elif part is ParameterList -%} +{{ oset_parameter_list(oset, part.kind) }} +{% elif part is Table -%} +{{ comps.table(part) }} +{%- else -%} +{{ part.unhandled_type() }} +{%- endif -%} +{%- endfor -%} +{%- endmacro %} + +{% macro oset_parameter_list(oset, kind) -%} +{%- set ns = namespace(title="", col="") -%} +{%- if kind == ParameterList.Parameters -%} + {%- set ns.title = "Parameters" -%} + {%- set ns.col1 = "Name" -%} + {%- set ns.col2 = "Description" -%} +{%- elif kind == ParameterList.TemplateParameters -%} + {%- set ns.title = "Template Parameters" -%} + {%- set ns.col1 = "Type" -%} + {%- set ns.col2 = "Description" -%} +{%- elif kind == ParameterList.Exceptions -%} + {%- set ns.title = "Exceptions" -%} + {%- set ns.col1 = "Type" -%} + {%- set ns.col2 = "Thrown On" -%} +{%- elif kind == ParameterList.ReturnValues -%} + {%- set ns.title = "Return Values" -%} + {%- set ns.col1 = "Type" -%} + {%- set ns.col2 = "Description" -%} +{%- endif -%} + +{%- set params = [] -%} +{%- for func in oset -%} + {%- for part in func.description -%} + {%- if part is ParameterList and part.kind == kind -%} + {%- for param in part -%} + {%- set name = param | map(attribute="name") + | map(attribute="text") | join -%} + {%- set type = param | map(attribute="type") + | map(attribute="text") | join -%} + {%- set names = params | map("map", attribute="name") + | map("map", attribute="text") | map("join") -%} + {%- set types = params | map("map", attribute="type") + | map("map", attribute="text") | map("join") -%} + {%- if (name not in names) or (type not in types) -%} + {%- set ___ = params.append(param) -%} + {%- endif -%} + {%- endfor -%} + {%- endif -%} + {%- endfor -%} +{%- endfor -%} + +{% call(param_block) comps.summary_table(params, ns.title, cols=[ns.col1, ns.col2]) -%} +{%- set sep = joiner(", ") %}[ +{%- for item in param_block -%} +{{ sep() }}` +{%- if item.type %}{{ comps.phrase(item.type) }} {% endif -%} +{{ comps.phrase(item.name) }}` +{%- endfor %} + ] + [ +{{ comps.description(param_block.description) }} + ] +{%- endcall -%} + +{%- endmacro %} + +{% for entity in entities.values() -%} + {% if entity is not Namespace -%} + {% continue %} + {%- endif -%} + {% if Config.default_namespace + and entity.fully_qualified_name != Config.default_namespace -%} + {% continue %} + {%- endif -%} + + {{ write_namespace(entity) }} +{%- endfor %} diff --git a/include/boost/json/parse.hpp b/include/boost/json/parse.hpp index 538d5c85c..c1309becd 100644 --- a/include/boost/json/parse.hpp +++ b/include/boost/json/parse.hpp @@ -23,39 +23,43 @@ namespace json { /** Return parsed JSON as a @ref value. - This function parses an entire string in one - step to produce a complete JSON object, returned - as a @ref value. If the buffer does not contain a - complete serialized JSON, an error occurs. In this - case the returned value will be null, using the - [default memory resource]. + This function parses input in one step to produce a complete JSON + @ref value. If the input does not contain a complete serialized JSON, an + error occurs. In this case (1), (2), (4), and (5) return a null value that + uses the [default memory resource], and set `ec` to the corresponding error + value. (3) and (6) throw an exception. @par Complexity - Linear in `s.size()`. + @li (1), (2), (3) linear in `s.size()`. + @li (4), (5), (6) linear in the size of consumed input. @par Exception Safety - Strong guarantee. + @li (1), (2), (3) strong guarantee. + @li (4), (5), (6) basic guarantee. + + (3), (6) throw `boost::system::system_error` on failed parse. Calls to `memory_resource::allocate` may throw. + The stream `is` may throw as described by [`std::ios::exceptions`]. - @return A value representing the parsed JSON, - or a null if any error occurred. + @return A value representing the parsed JSON. @param s The string to parse. @param ec Set to the error, if any occurred. - @param sp The memory resource that the new value and all - of its elements will use. If this parameter is omitted, - the [default memory resource] is used. + @param sp The memory resource that the new value and all of its elements + will use. If this parameter is omitted, the [default memory resource] + is used. + + @param opt The options for the parser. If this parameter is omitted, + the parser will accept only standard JSON. - @param opt The options for the parser. If this parameter - is omitted, the parser will accept only standard JSON. + @throw boost::system::system_error Thrown on failure: (3), (6). - @see - @ref parse_options, - @ref stream_parser. + @see @ref parse_options, @ref stream_parser, @ref value::operator>>. [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource + [`std::ios::exceptions`]: https://en.cppreference.com/w/cpp/io/basic_ios/exceptions */ /** @{ */ BOOST_JSON_DECL @@ -66,6 +70,7 @@ parse( storage_ptr sp = {}, parse_options const& opt = {}); +/// Overload BOOST_JSON_DECL value parse( @@ -73,42 +78,8 @@ parse( std::error_code& ec, storage_ptr sp = {}, parse_options const& opt = {}); -/** @} */ - -/** Return parsed JSON as a @ref value. - - This function parses an entire string in one - step to produce a complete JSON object, returned - as a @ref value. If the buffer does not contain a - complete serialized JSON, an exception is thrown. - - @par Complexity - Linear in `s.size()`. - - @par Exception Safety - Strong guarantee. - Calls to `memory_resource::allocate` may throw. - - @return A value representing the parsed - JSON upon success. - - @param s The string to parse. - @param sp The memory resource that the new value and all - of its elements will use. If this parameter is omitted, - the [default memory resource] is used. - - @param opt The options for the parser. If this parameter - is omitted, the parser will accept only standard JSON. - - @throw boost::system::system_error Thrown on failure. - - @see - @ref parse_options, - @ref stream_parser. - - [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource -*/ +/// Overload BOOST_JSON_DECL value parse( @@ -116,42 +87,12 @@ parse( storage_ptr sp = {}, parse_options const& opt = {}); -/** Return parsed JSON as a @ref value. - - This function reads data from an input stream and parses it to produce a - complete JSON entity, returned as a @ref value. If the stream does not - contain a complete serialized JSON, or contains extra non-whitespace data, - an error occurs. In this case the returned value will be `null`, using the - [default memory resource]. - - @par Complexity - Linear in the size of consumed input. - - @par Exception Safety - Basic guarantee. - Calls to `memory_resource::allocate` may throw. - The stream may throw as described by - [`std::ios::exceptions`](https://en.cppreference.com/w/cpp/io/basic_ios/exceptions). - - @return A value representing the parsed JSON, - or a `null` if any error occurred. - +/** Overload @param is The stream to read from. - - @param ec Set to the error, if any occurred. - - @param sp The memory resource that the new value and all of its elements - will use. If this parameter is omitted, the [default memory resource] - is used. - - @param opt The options for the parser. If this parameter is omitted, the - parser will accept only standard JSON. - - @see @ref parse_options, @ref stream_parser, @ref value::operator>>. - - [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource + @param ec + @param sp + @param opt */ -/** @{ */ BOOST_JSON_DECL value parse( @@ -160,6 +101,7 @@ parse( storage_ptr sp = {}, parse_options const& opt = {}); +/// Overload BOOST_JSON_DECL value parse( @@ -167,46 +109,15 @@ parse( std::error_code& ec, storage_ptr sp = {}, parse_options const& opt = {}); -/** @} */ - -/** Return parsed JSON as a @ref value. - - This function reads data from an input stream and parses it to produce a - complete JSON entity, returned as a @ref value. If the stream does not - contain a complete serialized JSON, or contains extra non-whitespace data, - an exception is thrown. - - @par Complexity - Linear in the size of consumed input. - - @par Exception Safety - Basic guarantee. - Throws `boost::system::system_error` on failed parse. - Calls to `memory_resource::allocate` may throw. - The stream may throw as described by - [`std::ios::exceptions`](https://en.cppreference.com/w/cpp/io/basic_ios/exceptions). - @return A value representing the parsed JSON upon success. - - @param is The stream to read from. - - @param sp The memory resource that the new value and all of its elements - will use. If this parameter is omitted, the [default memory resource] - is used. - - @param opt The options for the parser. If this parameter is omitted, the - parser will accept only standard JSON. - - @see @ref parse_options, @ref stream_parser, @ref value::operator>>. - - [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource -*/ +/// Overload BOOST_JSON_DECL value parse( std::istream& is, storage_ptr sp = {}, parse_options const& opt = {}); +/** @} */ } // namespace json } // namespace boost From 6659b905fdf0f78c62fe6209fab1985775b33d59 Mon Sep 17 00:00:00 2001 From: Dmitry Arkhipov Date: Mon, 15 Jul 2024 20:08:20 +0300 Subject: [PATCH 2/2] fix external types --- doc/externals.hpp | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/externals.hpp b/doc/externals.hpp index 32f7e320c..5b0e48c9a 100644 --- a/doc/externals.hpp +++ b/doc/externals.hpp @@ -6,7 +6,7 @@ namespace boost { /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/assert/doc/html/assert.html#source_location -using source_location = void; +struct source_location {}; namespace container { namespace pmr { @@ -15,12 +15,12 @@ namespace pmr { /// /// @see https://www.boost.org/doc/libs/release/doc/html/boost/container/pmr/polymorphic_allocator.html template -using polymorphic_allocator = void; +struct polymorphic_allocator {}; /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/1_85_0/doc/html/boost/container/pmr/memory_resource.html -using memory_resource = void; +struct memory_resource {}; } // namespace pmr } // namespace container @@ -30,27 +30,27 @@ namespace system { /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_error_code -using error_code = void; +struct error_code {}; /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_error_category -using error_category = void; +struct error_category {}; /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_error_condition -using error_condition = void; +struct error_condition {}; /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_system_error -using system_error = void; +struct system_error {}; /// !EXTERNAL! /// /// @see https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_boostsystemresult_hpp -using result = void; +struct result {}; } // namespace system } // namespace boost @@ -61,62 +61,62 @@ namespace std { /// /// @see https://en.cppreference.com/w/cpp/iterator/reverse_iterator template -using reverse_iterator = void; +struct reverse_iterator {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/size_t -using size_t = void; +struct size_t {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/integer -using uint64_t = void; +struct uint64_t {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/integer -using int64_t = void; +struct int64_t {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/nullptr_t -using nullptr_t = void; +struct nullptr_t {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/ptrdiff_t -using ptrdiff_t = void; +struct ptrdiff_t {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/utility/initializer_list template -using initializer_list= void; +struct initializer_list {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/error/error_code -using error_code = void; +struct error_code {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/utility/pair -using pair = void; +struct pair {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/types/byte -using byte = void; +struct byte {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/io/basic_ostream -using ostream = void; +struct ostream {}; /// !EXTERNAL! /// /// @see https://en.cppreference.com/w/cpp/io/basic_istream -using istream = void; +struct istream {}; } // namespace std