Hu Chunming / sip_server

//
// 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}]

*/