3party/jsoncpp
0
0
Fork 0
mirror of https://github.com/open-source-parsers/jsoncpp.git synced 2024-12-27 11:21:02 +08:00
Code Issues Projects Releases Wiki Activity

Improve code comment formatting (Issue #985)

Browse Source
This commit is contained in:
Billy Donahue 2019-07-14 18:41:48 -04:00 committed by Jordan Bayles
parent b3507948e2
commit 483eba84a7
3 changed files with 189 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

251
include/json/reader.h
View File

@ -28,7 +28,7 @@
namespace Json { namespace Json {
/** \brief Unserialize a <a HREF="http://www.json.org">JSON</a> document into a /** \brief Unserialize a <a HREF="http://www.json.org">JSON</a> document into a
*Value. * Value.
* *
* \deprecated Use CharReader and CharReaderBuilder. * \deprecated Use CharReader and CharReaderBuilder.
*/ */
@ -41,7 +41,6 @@ public:
* *
* The offsets give the [start, limit) range of bytes within the text. Note * The offsets give the [start, limit) range of bytes within the text. Note
* that this is bytes, not codepoints. * that this is bytes, not codepoints.
*
*/ */
struct StructuredError { struct StructuredError {
ptrdiff_t offset_start; ptrdiff_t offset_start;
@ -49,29 +48,27 @@ public:
String message; String message;
}; };
/** \brief Constructs a Reader allowing all features /** \brief Constructs a Reader allowing all features for parsing.
* for parsing.
*/ */
JSONCPP_DEPRECATED("Use CharReader and CharReaderBuilder instead") JSONCPP_DEPRECATED("Use CharReader and CharReaderBuilder instead")
Reader(); Reader();
/** \brief Constructs a Reader allowing the specified feature set /** \brief Constructs a Reader allowing the specified feature set for parsing.
* for parsing.
*/ */
JSONCPP_DEPRECATED("Use CharReader and CharReaderBuilder instead") JSONCPP_DEPRECATED("Use CharReader and CharReaderBuilder instead")
Reader(const Features& features); Reader(const Features& features);
/** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a> /** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a>
* document. * document.
* \param document UTF-8 encoded string containing the document to read. *
* \param root [out] Contains the root value of the document if it was * \param document UTF-8 encoded string containing the document
* successfully parsed. * to read.
* \param collectComments \c true to collect comment and allow writing them * \param[out] root Contains the root value of the document if it
* back during * was successfully parsed.
* serialization, \c false to discard comments. * \param collectComments \c true to collect comment and allow writing
* This parameter is ignored if * them back during serialization, \c false to
* Features::allowComments_ * discard comments. This parameter is ignored
* is \c false. * if Features::allowComments_ is \c false.
* \return \c true if the document was successfully parsed, \c false if an * \return \c true if the document was successfully parsed, \c false if an
* error occurred. * error occurred.
*/ */
@ -79,22 +76,20 @@ public:
parse(const std::string& document, Value& root, bool collectComments = true); parse(const std::string& document, Value& root, bool collectComments = true);
/** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a> /** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a>
document. * document.
* \param beginDoc Pointer on the beginning of the UTF-8 encoded string of the *
document to read. * \param beginDoc Pointer on the beginning of the UTF-8 encoded
* \param endDoc Pointer on the end of the UTF-8 encoded string of the * string of the document to read.
document to read. * \param endDoc Pointer on the end of the UTF-8 encoded string
* Must be >= beginDoc. * of the document to read. Must be >= beginDoc.
* \param root [out] Contains the root value of the document if it was * \param[out] root Contains the root value of the document if it
* successfully parsed. * was successfully parsed.
* \param collectComments \c true to collect comment and allow writing them * \param collectComments \c true to collect comment and allow writing
back during * them back during serialization, \c false to
* serialization, \c false to discard comments. * discard comments. This parameter is ignored
* This parameter is ignored if * if Features::allowComments_ is \c false.
Features::allowComments_
* is \c false.
* \return \c true if the document was successfully parsed, \c false if an * \return \c true if the document was successfully parsed, \c false if an
error occurred. * error occurred.
*/ */
bool parse(const char* beginDoc, bool parse(const char* beginDoc,
const char* endDoc, const char* endDoc,
@ -107,11 +102,10 @@ public:
/** \brief Returns a user friendly string that list errors in the parsed /** \brief Returns a user friendly string that list errors in the parsed
* document. * document.
* \return Formatted error message with the list of errors with their location *
* in * \return Formatted error message with the list of errors with their
* the parsed document. An empty string is returned if no error * location in the parsed document. An empty string is returned if no error
* occurred * occurred during parsing.
* during parsing.
* \deprecated Use getFormattedErrorMessages() instead (typo fix). * \deprecated Use getFormattedErrorMessages() instead (typo fix).
*/ */
JSONCPP_DEPRECATED("Use getFormattedErrorMessages() instead.") JSONCPP_DEPRECATED("Use getFormattedErrorMessages() instead.")
@ -119,32 +113,33 @@ public:
/** \brief Returns a user friendly string that list errors in the parsed /** \brief Returns a user friendly string that list errors in the parsed
* document. * document.
* \return Formatted error message with the list of errors with their location *
* in * \return Formatted error message with the list of errors with their
* the parsed document. An empty string is returned if no error * location in the parsed document. An empty string is returned if no error
* occurred * occurred during parsing.
* during parsing.
*/ */
String getFormattedErrorMessages() const; String getFormattedErrorMessages() const;
/** \brief Returns a vector of structured erros encounted while parsing. /** \brief Returns a vector of structured erros encounted while parsing.
*
* \return A (possibly empty) vector of StructuredError objects. Currently * \return A (possibly empty) vector of StructuredError objects. Currently
* only one error can be returned, but the caller should tolerate * only one error can be returned, but the caller should tolerate multiple
* multiple * errors. This can occur if the parser recovers from a non-fatal parse
* errors. This can occur if the parser recovers from a non-fatal * error and then encounters additional errors.
* parse error and then encounters additional errors.
*/ */
std::vector<StructuredError> getStructuredErrors() const; std::vector<StructuredError> getStructuredErrors() const;
/** \brief Add a semantic error message. /** \brief Add a semantic error message.
*
* \param value JSON Value location associated with the error * \param value JSON Value location associated with the error
* \param message The error message. * \param message The error message.
* \return \c true if the error was successfully added, \c false if the * \return \c true if the error was successfully added, \c false if the Value
* Value offset exceeds the document size. * offset exceeds the document size.
*/ */
bool pushError(const Value& value, const String& message); bool pushError(const Value& value, const String& message);
/** \brief Add a semantic error message with extra context. /** \brief Add a semantic error message with extra context.
*
* \param value JSON Value location associated with the error * \param value JSON Value location associated with the error
* \param message The error message. * \param message The error message.
* \param extra Additional JSON Value location to contextualize the error * \param extra Additional JSON Value location to contextualize the error
@ -154,8 +149,9 @@ public:
bool pushError(const Value& value, const String& message, const Value& extra); bool pushError(const Value& value, const String& message, const Value& extra);
/** \brief Return whether there are any errors. /** \brief Return whether there are any errors.
* \return \c true if there are no errors to report \c false if *
* errors have occurred. * \return \c true if there are no errors to report \c false if errors have
* occurred.
*/ */
bool good() const; bool good() const;
@ -255,22 +251,20 @@ class JSON_API CharReader {
public: public:
virtual ~CharReader() = default; virtual ~CharReader() = default;
/** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a> /** \brief Read a Value from a <a HREF="http://www.json.org">JSON</a>
document. * document. The document must be a UTF-8 encoded string containing the
* The document must be a UTF-8 encoded string containing the document to * document to read.
read.
* *
* \param beginDoc Pointer on the beginning of the UTF-8 encoded string of the * \param beginDoc Pointer on the beginning of the UTF-8 encoded string
document to read. * of the document to read.
* \param endDoc Pointer on the end of the UTF-8 encoded string of the * \param endDoc Pointer on the end of the UTF-8 encoded string of the
document to read. * document to read. Must be >= beginDoc.
* Must be >= beginDoc. * \param[out] root Contains the root value of the document if it was
* \param root [out] Contains the root value of the document if it was
* successfully parsed. * successfully parsed.
* \param errs [out] Formatted error messages (if not NULL) * \param[out] errs Formatted error messages (if not NULL) a user
* a user friendly string that lists errors in the parsed * friendly string that lists errors in the parsed
* document. * document.
* \return \c true if the document was successfully parsed, \c false if an * \return \c true if the document was successfully parsed, \c false if an
error occurred. * error occurred.
*/ */
virtual bool parse(char const* beginDoc, virtual bool parse(char const* beginDoc,
char const* endDoc, char const* endDoc,
@ -288,58 +282,57 @@ public:
}; // CharReader }; // CharReader
/** \brief Build a CharReader implementation. /** \brief Build a CharReader implementation.
*
Usage: * Usage:
\code * \code
using namespace Json; * using namespace Json;
CharReaderBuilder builder; * CharReaderBuilder builder;
builder["collectComments"] = false; * builder["collectComments"] = false;
Value value; * Value value;
String errs; * String errs;
bool ok = parseFromStream(builder, std::cin, &value, &errs); * bool ok = parseFromStream(builder, std::cin, &value, &errs);
\endcode * \endcode
*/ */
class JSON_API CharReaderBuilder : public CharReader::Factory { class JSON_API CharReaderBuilder : public CharReader::Factory {
public: public:
// Note: We use a Json::Value so that we can add data-members to this class // Note: We use a Json::Value so that we can add data-members to this class
// without a major version bump. // without a major version bump.
/** Configuration of this builder. /** Configuration of this builder.
These are case-sensitive. * These are case-sensitive.
Available settings (case-sensitive): * Available settings (case-sensitive):
- `"collectComments": false or true` * - `"collectComments": false or true`
- true to collect comment and allow writing them * - true to collect comment and allow writing them back during
back during serialization, false to discard comments. * serialization, false to discard comments. This parameter is ignored
This parameter is ignored if allowComments is false. * if allowComments is false.
- `"allowComments": false or true` * - `"allowComments": false or true`
- true if comments are allowed. * - true if comments are allowed.
- `"strictRoot": false or true` * - `"strictRoot": false or true`
- true if root must be either an array or an object value * - true if root must be either an array or an object value
- `"allowDroppedNullPlaceholders": false or true` * - `"allowDroppedNullPlaceholders": false or true`
- true if dropped null placeholders are allowed. (See * - true if dropped null placeholders are allowed. (See
StreamWriterBuilder.) * StreamWriterBuilder.)
- `"allowNumericKeys": false or true` * - `"allowNumericKeys": false or true`
- true if numeric object keys are allowed. * - true if numeric object keys are allowed.
- `"allowSingleQuotes": false or true` * - `"allowSingleQuotes": false or true`
- true if '' are allowed for strings (both keys and values) * - true if '' are allowed for strings (both keys and values)
- `"stackLimit": integer` * - `"stackLimit": integer`
- Exceeding stackLimit (recursive depth of `readValue()`) will * - Exceeding stackLimit (recursive depth of `readValue()`) will cause an
cause an exception. * exception.
- This is a security issue (seg-faults caused by deeply nested JSON), * - This is a security issue (seg-faults caused by deeply nested JSON), so
so the default is low. * the default is low.
- `"failIfExtra": false or true` * - `"failIfExtra": false or true`
- If true, `parse()` returns false when extra non-whitespace trails * - If true, `parse()` returns false when extra non-whitespace trails the
the JSON value in the input string. * JSON value in the input string.
- `"rejectDupKeys": false or true` * - `"rejectDupKeys": false or true`
- If true, `parse()` returns false when a key is duplicated within an * - If true, `parse()` returns false when a key is duplicated within an
object. * object.
- `"allowSpecialFloats": false or true` * - `"allowSpecialFloats": false or true`
- If true, special float values (NaNs and infinities) are allowed * - If true, special float values (NaNs and infinities) are allowed and
and their values are lossfree restorable. * their values are lossfree restorable.
*
You can examine 'settings_` yourself * You can examine 'settings_` yourself to see the defaults. You can also
to see the defaults. You can also write and read them just like any * write and read them just like any JSON Value.
JSON Value. * \sa setDefaults()
\sa setDefaults()
*/ */
Json::Value settings_; Json::Value settings_;
@ -381,29 +374,29 @@ bool JSON_API parseFromStream(CharReader::Factory const&,
String* errs); String* errs);
/** \brief Read from 'sin' into 'root'. /** \brief Read from 'sin' into 'root'.
*
Always keep comments from the input JSON. * Always keep comments from the input JSON.
*
This can be used to read a file into a particular sub-object. * This can be used to read a file into a particular sub-object.
For example: * For example:
\code * \code
Json::Value root; * Json::Value root;
cin >> root["dir"]["file"]; * cin >> root["dir"]["file"];
cout << root; * cout << root;
\endcode * \endcode
Result: * Result:
\verbatim * \verbatim
{ * {
"dir": { * "dir": {
"file": { * "file": {
// The input stream JSON would be nested here. * // The input stream JSON would be nested here.
} * }
} * }
} * }
\endverbatim * \endverbatim
\throw std::exception on parse error. * \throw std::exception on parse error.
\see Json::operator<<() * \see Json::operator<<()
*/ */
JSON_API IStream& operator>>(IStream&, Value&); JSON_API IStream& operator>>(IStream&, Value&);
} // namespace Json } // namespace Json

96
include/json/value.h
View File

@ -280,20 +280,21 @@ public:
#endif // ifndef JSONCPP_DOC_EXCLUDE_IMPLEMENTATION #endif // ifndef JSONCPP_DOC_EXCLUDE_IMPLEMENTATION
public: public:
/** \brief Create a default Value of the given type. /**
* \brief Create a default Value of the given type.
This is a very useful constructor. *
To create an empty array, pass arrayValue. * This is a very useful constructor.
To create an empty object, pass objectValue. * To create an empty array, pass arrayValue.
Another Value can then be set to this one by assignment. * To create an empty object, pass objectValue.
This is useful since clear() and resize() will not alter types. * Another Value can then be set to this one by assignment.
* This is useful since clear() and resize() will not alter types.
Examples: *
\code * Examples:
Json::Value null_value; // null * \code
Json::Value arr_value(Json::arrayValue); // [] * Json::Value null_value; // null
Json::Value obj_value(Json::objectValue); // {} * Json::Value arr_value(Json::arrayValue); // []
\endcode * Json::Value obj_value(Json::objectValue); // {}
* \endcode
*/ */
Value(ValueType type = nullValue); Value(ValueType type = nullValue);
Value(Int value); Value(Int value);
@ -305,14 +306,16 @@ Json::Value obj_value(Json::objectValue); // {}
Value(double value); Value(double value);
Value(const char* value); ///< Copy til first 0. (NULL causes to seg-fault.) Value(const char* value); ///< Copy til first 0. (NULL causes to seg-fault.)
Value(const char* begin, const char* end); ///< Copy all, incl zeroes. Value(const char* begin, const char* end); ///< Copy all, incl zeroes.
/** \brief Constructs a value from a static string. /**
* \brief Constructs a value from a static string.
*
* Like other value string constructor but do not duplicate the string for * Like other value string constructor but do not duplicate the string for
* internal storage. The given string must remain alive after the call to this * internal storage. The given string must remain alive after the call to
* constructor. * this constructor.
*
* \note This works only for null-terminated strings. (We cannot change the * \note This works only for null-terminated strings. (We cannot change the
* size of this class, so we have nowhere to store the length, * size of this class, so we have nowhere to store the length, which might be
* which might be computed later for various operations.) * computed later for various operations.)
* *
* Example of usage: * Example of usage:
* \code * \code
@ -321,8 +324,7 @@ Json::Value obj_value(Json::objectValue); // {}
* \endcode * \endcode
*/ */
Value(const StaticString& value); Value(const StaticString& value);
Value(const String& value); ///< Copy data() til size(). Embedded Value(const String& value);
///< zeroes too.
#ifdef JSON_USE_CPPTL #ifdef JSON_USE_CPPTL
Value(const CppTL::ConstString& value); Value(const CppTL::ConstString& value);
#endif #endif
@ -419,35 +421,26 @@ Json::Value obj_value(Json::objectValue); // {}
/// \post type() is arrayValue /// \post type() is arrayValue
void resize(ArrayIndex newSize); void resize(ArrayIndex newSize);
/// Access an array element (zero based index ). //@{
/// If the array contains less than index element, then null value are /// Access an array element (zero based index). If the array contains less
/// inserted /// than index element, then null value are inserted in the array so that
/// in the array so that its size is index+1. /// its size is index+1.
/// (You may need to say 'value[0u]' to get your compiler to distinguish /// (You may need to say 'value[0u]' to get your compiler to distinguish
/// this from the operator[] which takes a string.) /// this from the operator[] which takes a string.)
Value& operator[](ArrayIndex index); Value& operator[](ArrayIndex index);
/// Access an array element (zero based index ).
/// If the array contains less than index element, then null value are
/// inserted
/// in the array so that its size is index+1.
/// (You may need to say 'value[0u]' to get your compiler to distinguish
/// this from the operator[] which takes a string.)
Value& operator[](int index); Value& operator[](int index);
//@}
/// Access an array element (zero based index ) //@{
/// Access an array element (zero based index).
/// (You may need to say 'value[0u]' to get your compiler to distinguish /// (You may need to say 'value[0u]' to get your compiler to distinguish
/// this from the operator[] which takes a string.) /// this from the operator[] which takes a string.)
const Value& operator[](ArrayIndex index) const; const Value& operator[](ArrayIndex index) const;
/// Access an array element (zero based index )
/// (You may need to say 'value[0u]' to get your compiler to distinguish
/// this from the operator[] which takes a string.)
const Value& operator[](int index) const; const Value& operator[](int index) const;
//@}
/// If the array contains at least index+1 elements, returns the element /// If the array contains at least index+1 elements, returns the element
/// value, /// value, otherwise returns defaultValue.
/// otherwise returns defaultValue.
Value get(ArrayIndex index, const Value& defaultValue) const; Value get(ArrayIndex index, const Value& defaultValue) const;
/// Return true if index < size(). /// Return true if index < size().
bool isValidIndex(ArrayIndex index) const; bool isValidIndex(ArrayIndex index) const;
@ -472,11 +465,10 @@ Json::Value obj_value(Json::objectValue); // {}
/// \param key may contain embedded nulls. /// \param key may contain embedded nulls.
const Value& operator[](const String& key) const; const Value& operator[](const String& key) const;
/** \brief Access an object value by name, create a null member if it does not /** \brief Access an object value by name, create a null member if it does not
exist. * exist.
*
* If the object has no entry for that name, then the member name used to * If the object has no entry for that name, then the member name used to
store * store the new entry is not duplicated.
* the new entry is not duplicated.
* Example of use: * Example of use:
* \code * \code
* Json::Value object; * Json::Value object;
@ -530,19 +522,19 @@ Json::Value obj_value(Json::objectValue); // {}
/// but 'key' is null-terminated. /// but 'key' is null-terminated.
bool removeMember(const char* key, Value* removed); bool removeMember(const char* key, Value* removed);
/** \brief Remove the named map member. /** \brief Remove the named map member.
*
Update 'removed' iff removed. * Update 'removed' iff removed.
\param key may contain embedded nulls. * \param key may contain embedded nulls.
\return true iff removed (no exceptions) * \return true iff removed (no exceptions)
*/ */
bool removeMember(String const& key, Value* removed); bool removeMember(String const& key, Value* removed);
/// Same as removeMember(String const& key, Value* removed) /// Same as removeMember(String const& key, Value* removed)
bool removeMember(const char* begin, const char* end, Value* removed); bool removeMember(const char* begin, const char* end, Value* removed);
/** \brief Remove the indexed array element. /** \brief Remove the indexed array element.
*
O(n) expensive operations. * O(n) expensive operations.
Update 'removed' iff removed. * Update 'removed' iff removed.
\return true if removed (no exceptions) * \return true if removed (no exceptions)
*/ */
bool removeIndex(ArrayIndex index, Value* removed); bool removeIndex(ArrayIndex index, Value* removed);

4
src/lib_json/json_value.cpp
View File

@ -235,9 +235,7 @@ LogicError::LogicError(String const& msg) : Exception(msg) {}
[[noreturn]] void throwRuntimeError(String const& msg) { [[noreturn]] void throwRuntimeError(String const& msg) {
throw RuntimeError(msg); throw RuntimeError(msg);
} }
[[noreturn]] void throwLogicError(String const& msg) { [[noreturn]] void throwLogicError(String const& msg) { throw LogicError(msg); }
throw LogicError(msg);
}
#else // !JSON_USE_EXCEPTION #else // !JSON_USE_EXCEPTION
[[noreturn]] void throwRuntimeError(String const& msg) { abort(); } [[noreturn]] void throwRuntimeError(String const& msg) { abort(); }
[[noreturn]] void throwLogicError(String const& msg) { abort(); } [[noreturn]] void throwLogicError(String const& msg) { abort(); }