594 lines
13 KiB
C++
594 lines
13 KiB
C++
|
//
|
||
|
|
// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
|
||
|
|
//
|
||
|
|
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||
|
|
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||
|
|
//
|
||
|
|
// Official repository: https://github.com/cppalliance/json
|
||
|
|
//
|
||
|
|
|
||
|
|
----------------------------- DOCUMENTATION STYLE GUIDE -------------------------------
|
||
|
|
|
||
|
|
Javadoc documentation shall be structured following the template below.
|
||
|
|
|
||
|
|
--------------------------------- GENERAL CONVENTIONS ---------------------------------
|
||
|
|
|
||
|
|
Except for a brief element, lines shall not exceed 60 characters in length.
|
||
|
|
|
||
|
|
Sentences shall be correctly punctuated. If a line ends in a code element, this
|
||
|
|
requirement still applies unless the code is part of a Exceptions, Parameters, or
|
||
|
|
Returns element.
|
||
|
|
|
||
|
|
In a code block, the unary negation operator shall be written using the alternative
|
||
|
|
token "not" when expression following it is not parenthesized and the negation
|
||
|
|
expression is not the operand of an operator.
|
||
|
|
|
||
|
|
With respect to iterators, when referring to an iterator that represents an object
|
||
|
|
(i.e. not past the end), the convention for doing so is to say the iterator "refers"
|
||
|
|
to the object. When referring to an iterator that is past-the-end of a range or
|
||
|
|
an object, the convention for doing so is "iterator one past the end of *X*",
|
||
|
|
where *X* is the range or object.
|
||
|
|
|
||
|
|
----------------------------------------- KEY -----------------------------------------
|
||
|
|
|
||
|
|
Names surrounded with braces corrospond to elements defined in the ELEMENTS section.
|
||
|
|
|
||
|
|
Bracket enclosed elements are optional. Certain elements have restrictions as to which
|
||
|
|
contexts they may appear in; if the requirement are not met, the element shall not
|
||
|
|
be present.
|
||
|
|
|
||
|
|
----------------------------------- GENERAL TEMPLATE ----------------------------------
|
||
|
|
|
||
|
|
Elements shall appear in the following order:
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Preconditions
|
||
|
|
|
||
|
|
{Preconditions}
|
||
|
|
|
||
|
|
|
||
|
|
@par Exception Safety
|
||
|
|
|
||
|
|
{Exception Safety}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Thread Safety
|
||
|
|
|
||
|
|
{Thread Safety}]
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
{Exceptions}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Satisfies
|
||
|
|
|
||
|
|
{Satisfies}]
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
--------------------------------------- ELEMENTS --------------------------------------
|
||
|
|
|
||
|
|
All of the following elements shall be present if the contextual requirements for
|
||
|
|
their appearance is met, and otherwise shall not appear. Optional elements
|
||
|
|
need not be present.
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
The following elements shall only be present for both types and functions.
|
||
|
|
|
||
|
|
--------------- BOTH ---------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Brief
|
||
|
|
Appearance: Shall be present for functions and types that are visible to the user.
|
||
|
|
|
||
|
|
Description: Always written in imperative voice, punctuate with a period. A short
|
||
|
|
sentence describing the functionality or use of the type or function, without
|
||
|
|
going into much depth. For functions with no side effects, preconditions,
|
||
|
|
thrown exceptions and parameters, this should state what the function returns;
|
||
|
|
further description can be done as a remark. For functions with side effects, it
|
||
|
|
should be a synopsis of what the function does. For class types, it should describe
|
||
|
|
what the class does, and for type aliases it should describe what the type represents.
|
||
|
|
|
||
|
|
Length requirement: Length should be no more than 200 characters.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Description
|
||
|
|
Appearance: This should be included if the brief and remarks are not sufficient
|
||
|
|
to describe what the entity does. This shall not be present for type aliases,
|
||
|
|
or function that have no side effects.
|
||
|
|
|
||
|
|
Description: Sufficiently describes the function including all its effects upon its
|
||
|
|
parameters (if of reference or pointer type), the object it is called upon, or an
|
||
|
|
object that the called upon object holds a reference or pointer to (in short, any
|
||
|
|
side-effects that are immediately obvious from the call site).
|
||
|
|
Does not specify exceptions.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Template Parameters
|
||
|
|
Appearance: Shall be present for templates. Shall not be present
|
||
|
|
for template parameters whose sole purpose is SFINAE.
|
||
|
|
|
||
|
|
Description: Describes what the template parameter represents.
|
||
|
|
Default arguments shall be specified.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Constraints
|
||
|
|
Appearance: Shall be present for templated entities with constrained
|
||
|
|
template parameters
|
||
|
|
|
||
|
|
Description: For a templated entity that is a function or a function template,
|
||
|
|
this specifies under which conditions an overload participates in overload
|
||
|
|
resolution. For a templated entity that is a class or a class template,
|
||
|
|
this specified under which conditions an template-id referring to a
|
||
|
|
specialization is well-formed.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
------------- OPTIONAL -------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Remarks
|
||
|
|
Appearance: Optionally present if there are remarks to make outside of the description.
|
||
|
|
If no description or return value element exists, the content of this shall be
|
||
|
|
used as a description instead.
|
||
|
|
|
||
|
|
Description: For functions, this describes any side effects not covered by the
|
||
|
|
description (for example, iterator invalidation), or calls to function that can
|
||
|
|
potentially throw. For types, this is miscellaneous information not covered in the
|
||
|
|
description that does specify its functionality, but specifies extra
|
||
|
|
information or restrictions.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
See Also
|
||
|
|
Appearance: Optionally present for functions and class types
|
||
|
|
|
||
|
|
Description: Specifies function and class types that relate to the
|
||
|
|
function or class type, or other external resources relating to the entity
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
The following elements shall only be present for functions.
|
||
|
|
|
||
|
|
------------- FUNCTIONS -------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Preconditions
|
||
|
|
Appearance: Shall be present for functions with preconditions
|
||
|
|
|
||
|
|
Description: Specifies the preconditions of the function. When specifying the validity
|
||
|
|
of a range, this should be of the form "[x, y] is a valid range.", and otherwise should
|
||
|
|
take the form of a C++ expression.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Exception Safety
|
||
|
|
Appearance: Shall be present for functions that are potentially throwing
|
||
|
|
|
||
|
|
Description: Specifies the exception safety guarantee of the function. Shall be
|
||
|
|
one of: "Strong guarantee", "Basic guarantee", or "No guarantee".
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Return Value
|
||
|
|
Appearance: Shall be present for functions with a return type other than void
|
||
|
|
whose return value has not already been specified fully in the brief.
|
||
|
|
If no description element exists, the content of this shall be used as a description
|
||
|
|
instead (this will replace the description before the Remarks will). Shall not be
|
||
|
|
present for a constructor or destructor.
|
||
|
|
|
||
|
|
Description: Specifies the return value of the function
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Function Parameters
|
||
|
|
Appearance: Shall be present for functions that accept one or more parameters
|
||
|
|
|
||
|
|
Description: Describes the significance of each of the non-discarded function
|
||
|
|
parameters (i.e. not used to enact constraints), and specifies default
|
||
|
|
arguments, if any.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Exceptions
|
||
|
|
Appearance: Shall be present for functions that are potentially throwing
|
||
|
|
|
||
|
|
Description: Specifies which exceptions can potentially be directly
|
||
|
|
thrown by that function and under which conditions they are thrown.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
------------- OPTIONAL -------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Complexity
|
||
|
|
Appearance: Optionally present for functions
|
||
|
|
|
||
|
|
Description: Specifies the complexity of the function.
|
||
|
|
This is done in non-big O notation.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
The following elements shall only be present for class types.
|
||
|
|
|
||
|
|
------------- TYPES (OPTIONAL) -------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Thread Safety
|
||
|
|
Appearance: Optionally present for class types
|
||
|
|
|
||
|
|
Description: Specifies when the member function of a class may be called concurrently,
|
||
|
|
or if they cannot be called concurrently for the same object
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
Satisfies
|
||
|
|
Appearance: Optionally present for class types
|
||
|
|
|
||
|
|
Description: For standard library related types, this specifies
|
||
|
|
a list of relevant named requirements that this type meets.
|
||
|
|
---------------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
------------------------------ SPECIALIZED TEMPLATES ----------------------------------
|
||
|
|
|
||
|
|
------------- CLASS -------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Thread Safety
|
||
|
|
|
||
|
|
{Thread Safety}]
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Satisfies
|
||
|
|
|
||
|
|
{Satisfies}]
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
------------- NON-THROWING FUNCTION -------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Preconditions
|
||
|
|
|
||
|
|
{Preconditions}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
--------------- THROWING FUNCTION ---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Preconditions
|
||
|
|
|
||
|
|
{Preconditions}
|
||
|
|
|
||
|
|
|
||
|
|
@par Exception Safety
|
||
|
|
|
||
|
|
{Exception Safety}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
{Exceptions}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
------------- NON-THROWING FUNCTION TEMPLATE -------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Preconditions
|
||
|
|
|
||
|
|
{Preconditions}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
--------------- THROWING FUNCTION TEMPLATE ---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Preconditions
|
||
|
|
|
||
|
|
{Preconditions}
|
||
|
|
|
||
|
|
|
||
|
|
@par Exception Safety
|
||
|
|
|
||
|
|
{Exception Safety}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
{Exceptions}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
--------------- THROWING FUNCTION NO PRECONDITIONS---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Exception Safety
|
||
|
|
|
||
|
|
{Exception Safety}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
{Exceptions}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
--------------- THROWING FUNCTION TEMPLATE NO PRECONDITIONS ---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
@par Exception Safety
|
||
|
|
|
||
|
|
{Exception Safety}
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
{Exceptions}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
--------------- NON-THROWING FUNCTION NO PRECONDITIONS---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
--------------- NON-THROWING FUNCTION TEMPLATE NO PRECONDITIONS ---------------
|
||
|
|
|
||
|
|
/** {Brief}
|
||
|
|
|
||
|
|
{Description}
|
||
|
|
|
||
|
|
|
||
|
|
[@par Complexity
|
||
|
|
|
||
|
|
{Complexity}]
|
||
|
|
|
||
|
|
|
||
|
|
[@note
|
||
|
|
|
||
|
|
{Remarks}]
|
||
|
|
|
||
|
|
|
||
|
|
{Template Parameters}
|
||
|
|
|
||
|
|
{Constraints}
|
||
|
|
|
||
|
|
{Return Value}
|
||
|
|
|
||
|
|
{Function Parameters}
|
||
|
|
|
||
|
|
|
||
|
|
[@see
|
||
|
|
|
||
|
|
{See Also}]
|
||
|
|
|
||
|
|
*/
|