From 418a5829b311c3a0b1f4dc67ea7c26f240a57b12 Mon Sep 17 00:00:00 2001
From: "Philipp A. Hartmann" <pah@qo.cx>
Date: Wed, 9 Jul 2014 21:19:13 +0200
Subject: [PATCH] update documentation of ParseResult and related functions

---
 include/rapidjson/document.h    |  6 +++---
 include/rapidjson/error/error.h | 21 +++++++++++++++++++++
 include/rapidjson/reader.h      |  3 +++
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/include/rapidjson/document.h b/include/rapidjson/document.h
index b8d136d..042a2a3 100644
--- a/include/rapidjson/document.h
+++ b/include/rapidjson/document.h
@@ -1326,13 +1326,13 @@ public:
 	//!@name Handling parse errors
 	//!@{
 
-	//! Whether a parse error was occured in the last parsing.
+	//! Whether a parse error has occured in the last parsing.
 	bool HasParseError() const { return parseResult_.IsError(); }
 
-	//! Get the message of parsing error.
+	//! Get the \ref ParseErrorCode of last parsing.
 	ParseErrorCode GetParseError() const { return parseResult_.Code(); }
 
-	//! Get the offset in character of the parsing error.
+	//! Get the position of last parsing error in input, 0 otherwise.
 	size_t GetErrorOffset() const { return parseResult_.Offset(); }
 
 	//!@}
diff --git a/include/rapidjson/error/error.h b/include/rapidjson/error/error.h
index 765f1c1..829e2b9 100644
--- a/include/rapidjson/error/error.h
+++ b/include/rapidjson/error/error.h
@@ -59,22 +59,43 @@ enum ParseErrorCode {
 	kParseErrorNumberMissExponent				//!< Miss exponent in number.
 };
 
+//! Result of parsing (wraps ParseErrorCode)
+/*!
+	\code
+		Document doc;
+		ParseResult ok = doc.Parse("[42]");
+		if (!ok) {
+			fprintf(stderr, "JSON parse error: %s (%u)",
+					GetParseError_En(ok.Code()), ok.Offset());
+			exit(EXIT_FAILURE);
+		}
+	\endcode
+	\see GenericReader::Parse, GenericDocument::Parse
+*/
 struct ParseResult {
 
+	//! Default constructor, no error.
 	ParseResult() : code_(kParseErrorNone), offset_(0) {}
+	//! Constructor to set an error.
 	ParseResult(ParseErrorCode code, size_t offset) : code_(code), offset_(offset) {}
 
+	//! Get the error code.
 	ParseErrorCode Code() const { return code_; }
+	//! Get the error offset, if \ref IsError(), 0 otherwise.
 	size_t Offset() const { return offset_; }
 
+	//! Conversion to \c bool, returns \c true, iff !\ref IsError().
 	operator bool() const { return !IsError(); }
+	//! Whether the result is an error.
 	bool IsError() const { return code_ != kParseErrorNone; }
 
 	bool operator==(const ParseResult& that) const { return code_ == that.code_; }
 	bool operator==(ParseErrorCode code) const { return code_ == code; }
 	friend bool operator==(ParseErrorCode code, const ParseResult & err) { return code == err.code_; }
 
+	//! Reset error code.
 	void Clear() { Set(kParseErrorNone); }
+	//! Update error code and offset.
 	void Set(ParseErrorCode code, size_t offset = 0) { code_ = code; offset_ = offset; }
 
 private:
diff --git a/include/rapidjson/reader.h b/include/rapidjson/reader.h
index 72ebad9..0d77316 100644
--- a/include/rapidjson/reader.h
+++ b/include/rapidjson/reader.h
@@ -324,10 +324,13 @@ public:
 		return Parse<kParseDefaultFlags>(is, handler);
 	}
 
+	//! Whether a parse error has occured in the last parsing.
 	bool HasParseError() const { return parseResult_.IsError(); }
 	
+	//! Get the \ref ParseErrorCode of last parsing.
 	ParseErrorCode GetParseErrorCode() const { return parseResult_.Code(); }
 
+	//! Get the position of last parsing error in input, 0 otherwise.
 	size_t GetErrorOffset() const { return parseResult_.Offset(); }
 
 private: