[DOC] finish documentation

doc/write.md

@@ -63,7 +63,7 @@ Object concept                                    {#ejson_tutorial_concept}
 The ejson concept is to abstract the implementation of the internal system. All the element are mapped on shared memory.
 Then if you asign an element to an other, it is the same. You need to clone it if you want to have new standalone element.
 
-@snippet write.cpp ejson_sample_read_clone
+@snippet read.cpp ejson_sample_read_clone
 
 All example file                                  {#ejson_tutorial_write_all}
 ================

ejson/Array.h

@@ -12,6 +12,9 @@
 #include <ejson/iterator.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Array interface [ ... ].
+	 */
 	class Array : public ejson::Value {
 		public:
 			/**
@@ -31,6 +34,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Array& operator= (const ejson::Array& _obj);
 		public:
@@ -131,6 +135,7 @@ namespace ejson {
 			/**
 			 * @brief Remove Value with his iterator
 			 * @param[in] _it Iterator on the Value.
+			 * @return New valid iterator on the next element or this.end()
 			 */
 			iterator remove(const iterator& _it);
 	};

ejson/Boolean.h

@@ -11,6 +11,9 @@
 #include <ejson/Value.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Boolean interface: true/false.
+	 */
 	class Boolean : public ejson::Value {
 		public:
 			/**
@@ -31,6 +34,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Boolean& operator= (const ejson::Boolean& _obj);
 		public:

ejson/Document.cpp

@@ -67,20 +67,20 @@ bool ejson::Document::store(const std::string& _file) {
 	return static_cast<ejson::internal::Document*>(m_data.get())->store(_file);
 }
 
-void ejson::Document::displayErrorWhenDetected() {
+void setDisplayError(bool _value){
 	if (m_data == nullptr) {
-		EJSON_ERROR("Can not displayErrorWhenDetected (nullptr) ...");
+		EJSON_ERROR("Can not setDisplayError (nullptr) ...");
 		return;
 	}
-	static_cast<ejson::internal::Document*>(m_data.get())->displayErrorWhenDetected();
+	static_cast<ejson::internal::Document*>(m_data.get())->setDisplayError(_value);
 }
 
-void ejson::Document::notDisplayErrorWhenDetected() {
+bool getDisplayError() {
 	if (m_data == nullptr) {
-		EJSON_ERROR("Can not notDisplayErrorWhenDetected (nullptr) ...");
+		EJSON_ERROR("Can not getDisplayError (nullptr) ...");
-		return;
+		return false;
 	}
-	static_cast<ejson::internal::Document*>(m_data.get())->notDisplayErrorWhenDetected();
+	return static_cast<ejson::internal::Document*>(m_data.get())->getDisplayError(_value);
 }
 
 void ejson::Document::displayError() {

ejson/Document.h

@@ -15,6 +15,9 @@
 #include <ejson/Object.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Document interface (acces with the file and stream).
+	 */
 	class Document : public ejson::Object {
 		public:
 			/**
@@ -34,9 +37,9 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Document& operator= (const ejson::Document& _obj);
-		public:
 			/**
 			 * @brief parse a string that contain an XML
 			 * @param[in] _data Data to parse
@@ -65,9 +68,20 @@ namespace ejson {
 			 * @return true : Parsing is OK
 			 */
 			bool store(const std::string& _file);
-		public:
+			/**
-			void displayErrorWhenDetected();
+			 * @brief Set the display of the error when detected.
-			void notDisplayErrorWhenDetected();
+			 * @param[in] _value true: display error, false not display error (get it at end)
+			 */
+			void setDisplayError(bool _value);
+			/**
+			 * @brief Get the display of the error status.
+			 * @return true Display error
+			 * @return false Does not display error (get it at end)
+			 */
+			bool getDisplayError();
+			/**
+			 * @brief Display error detected.
+			 */
 			void displayError();
 	};
 }

ejson/Null.h

@@ -11,6 +11,9 @@
 #include <ejson/Value.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Null interface: 'null'.
+	 */
 	class Null : public ejson::Value {
 		public:
 			/**
@@ -30,6 +33,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Null& operator= (const ejson::Null& _obj);
 	};

ejson/Number.h

@@ -11,6 +11,9 @@
 #include <ejson/Value.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Number interface.
+	 */
 	class Number : public ejson::Value {
 		public:
 			/**
@@ -31,6 +34,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Number& operator= (const ejson::Number& _obj);
 			

ejson/Object.h

@@ -14,6 +14,9 @@
 #include <ejson/iterator.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson Object interface { ... }.
+	 */
 	class Object : public ejson::Value {
 		public:
 			/**
@@ -38,6 +41,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::Object& operator= (const ejson::Object& _obj);
 			
@@ -49,11 +53,16 @@ namespace ejson {
 			 */
 			bool valueExist(const std::string& _name) const;
 			/**
-			 * @brief get the sub element with his name (no cast check)
+			 * @brief Cet the sub element with his name (no cast check)
 			 * @param[in] _name Name of the object
-			 * @return pointer on the element requested or nullptr if it not the corect type or does not existed
+			 * @return Value on the element requested or a value that does not exist @ref ejson::Value::exist.
 			 */
 			ejson::Value operator[] (const std::string& _name);
+			/**
+			 * @brief Get the const sub element with his name (no cast check)
+			 * @param[in] _name Name of the object
+			 * @return const Value on the element requested or a value that does not exist @ref ejson::Value::exist.
+			 */
 			const ejson::Value operator[] (const std::string& _name) const;
 		public:
 			/**
@@ -67,11 +76,16 @@ namespace ejson {
 			 */
 			size_t size() const;
 			/**
-			 * @brief get the pointer on an element reference with his ID.
+			 * @brief Get the value on an element reference with his ID.
 			 * @param[in] _id Id of the element.
-			 * @return nullptr if the element does not exist.
+			 * @return Value on the element requested or a value that does not exist @ref ejson::Value::exist.
 			 */
 			ejson::Value operator[] (size_t _id);
+			/**
+			 * @brief Get the const value on an element reference with his ID.
+			 * @param[in] _id Id of the element.
+			 * @return const Value on the element requested or a value that does not exist @ref ejson::Value::exist.
+			 */
 			const ejson::Value operator[] (size_t _id) const;
 			/**
 			 * @brief Get the element name (key).
@@ -170,6 +184,7 @@ namespace ejson {
 			/**
 			 * @brief Remove Value with his iterator
 			 * @param[in] _it Iterator on the Value.
+			 * @return New valid iterator on the next element or this.end()
 			 */
 			iterator remove(const iterator& _it);
 	};

ejson/String.h

@@ -11,6 +11,9 @@
 #include <ejson/Value.h>
 
 namespace ejson {
+	/**
+	 * @brief ejson String interface.
+	 */
 	class String : public ejson::Value {
 		public:
 			/**
@@ -31,6 +34,7 @@ namespace ejson {
 			/**
 			 * @brief Copy constructor
 			 * @param[in] _obj Object to copy
+			 * @return Local reference on this object
 			 */
 			ejson::String& operator= (const ejson::String& _obj);
 		public:

ejson/Value.h

@@ -31,8 +31,8 @@ namespace ejson {
 	 * @brief Basic main object of all json elements.
 	 */
 	class Value {
-		friend ejson::Array;
+		friend class ejson::Array;
-		friend ejson::Object;
+		friend class ejson::Object;
 		protected:
 			ememory::SharedPtr<ejson::internal::Value> m_data; //!< internal reference on a Value
 		public:

ejson/internal/Array.cpp

@@ -208,6 +208,18 @@ bool ejson::internal::Array::iGenerate(std::string& _data, size_t _indent) const
 	return true;
 }
 
+size_t ejson::internal::Array::size() const {
+	return m_value.size();
+}
+
+ememory::SharedPtr<ejson::internal::Value> ejson::internal::Array::get(size_t _id) {
+	return m_value[_id];
+}
+
+const ememory::SharedPtr<const ejson::internal::Value> ejson::internal::Array::get(size_t _id) const {
+	return m_value[_id];
+}
+
 bool ejson::internal::Array::add(ememory::SharedPtr<ejson::internal::Value> _element) {
 	if (_element == nullptr) {
 		EJSON_ERROR("Request add on an nullptr pointer");

ejson/internal/Array.h

@@ -12,6 +12,9 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Array internal data implementation.
+		 */
 		class Array : public ejson::internal::Value {
 			protected:
 				/**
@@ -21,6 +24,10 @@ namespace ejson {
 					m_type = ejson::valueType::array;
 				}
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::Array
+				 * @return A SharedPtr on the Array value
+				 */
 				static ememory::SharedPtr<Array> create();
 			private:
 				std::vector<ememory::SharedPtr<ejson::internal::Value> > m_value; //!< vector of sub elements
@@ -29,21 +36,19 @@ namespace ejson {
 				 * @brief get the number of sub element in the current one
 				 * @return the Number of stored element
 				 */
-				size_t size() const {
+				size_t size() const;
-					return m_value.size();
-				}
 				/**
 				 * @brief get the pointer on an element reference with his ID.
 				 * @param[in] _id Id of the element.
 				 * @return nullptr if the element does not exist.
 				 */
-				ememory::SharedPtr<ejson::internal::Value> get(size_t _id) {
+				ememory::SharedPtr<ejson::internal::Value> get(size_t _id);
-					return m_value[_id];
+				/**
-				}
+				 * @brief get the const pointer on an element reference with his ID.
-				//! @previous
+				 * @param[in] _id Id of the element.
-				const ememory::SharedPtr<const ejson::internal::Value> get(size_t _id) const{
+				 * @return nullptr if the element does not exist.
-					return m_value[_id];
+				 */
-				}
+				const ememory::SharedPtr<const ejson::internal::Value> get(size_t _id) const;
 				/**
 				 * @brief add an element on the array.
 				 * @param[in] _element element to add.

ejson/internal/Boolean.h

@@ -12,13 +12,22 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Boolean internal data implementation.
+		 */
 		class Boolean : public ejson::internal::Value {
 			protected:
 				/**
 				 * @brief basic element of a xml structure
+				 * @param[in] _value Value to set on the Element
 				 */
 				Boolean(bool _value=false);
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::Boolean
+				 * @param[in] _value Value to set on the ejson::Value
+				 * @return A SharedPtr on the Boolean value
+				 */
 				static ememory::SharedPtr<Boolean> create(bool _value=false);
 			protected:
 				bool m_value; //!< value of the node

ejson/internal/Document.cpp

@@ -119,28 +119,6 @@ static std::string createPosPointer(const std::string& _line, size_t _pos) {
 	return out;
 }
 
-void ejson::internal::Document::displayError() {
-	if (m_comment.size() == 0) {
-		EJSON_ERROR("No error detected ???");
-		return;
-	}
-	EJSON_ERROR(m_filePos << " " << m_comment << "\n"
-	           << m_Line << "\n"
-	           << createPosPointer(m_Line, m_filePos.getCol()) );
-	#ifdef ENABLE_CRITICAL_WHEN_ERROR
-		EJSON_CRITICAL("detect error");
-	#endif
-}
-
-void ejson::internal::Document::createError(const std::string& _data, size_t _pos, const ejson::FilePos& _filePos, const std::string& _comment) {
-	m_comment = _comment;
-	m_Line = etk::extract_line(_data, _pos);
-	m_filePos = _filePos;
-	if (true == m_writeErrorWhenDetexted) {
-		displayError();
-	}
-}
-
 bool ejson::internal::Document::iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) {
 	EJSON_PARSE_ELEMENT("start parse : 'Document' ");
 	bool haveMainNode=false;
@@ -194,3 +172,37 @@ bool ejson::internal::Document::iParse(const std::string& _data, size_t& _pos, e
 	return true;
 }
 
+
+void ejson::internal::Document::setDisplayError(bool _value) {
+	m_writeErrorWhenDetexted = _value;
+}
+
+bool ejson::internal::Document::getDisplayError() {
+	return m_writeErrorWhenDetexted;
+}
+
+void ejson::internal::Document::displayError() {
+	if (m_comment.size() == 0) {
+		EJSON_INFO("No error detected ???");
+		return;
+	}
+	EJSON_ERROR(m_filePos << " " << m_comment << "\n"
+	           << m_Line << "\n"
+	           << createPosPointer(m_Line, m_filePos.getCol()) );
+	#ifdef ENABLE_CRITICAL_WHEN_ERROR
+		EJSON_CRITICAL("detect error");
+	#endif
+}
+
+void ejson::internal::Document::createError(const std::string& _data,
+                                            size_t _pos,
+                                            const ejson::FilePos& _filePos,
+                                            const std::string& _comment) {
+	m_comment = _comment;
+	m_Line = etk::extract_line(_data, _pos);
+	m_filePos = _filePos;
+	if (m_writeErrorWhenDetexted == true) {
+		displayError();
+	}
+}
+

ejson/internal/Document.h

@@ -16,12 +16,19 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Document internal data implementation.
+		 */
 		class Document : public ejson::internal::Object {
 			public:
 				/**
 				 * @brief Constructor
 				 */
 				Document();
+				/**
+				 * @brief Create factory on the ejson::internal::Document
+				 * @return A SharedPtr on the Document value
+				 */
 				static ememory::SharedPtr<Document> create();
 			public:
 				/**
@@ -53,27 +60,57 @@ namespace ejson {
 				 */
 				bool store(const std::string& _file);
 			private:
-				bool m_writeErrorWhenDetexted;
+				bool m_writeErrorWhenDetexted; //!< Flag to know if we need to display error when they are detected
-				std::string m_comment;
+				std::string m_comment; //!< Error comment
-				std::string m_Line;
+				std::string m_Line; //!< Line with the error
-				ejson::FilePos m_filePos;
+				ejson::FilePos m_filePos; //!< Position in the file of the error
 			public:
-				void displayErrorWhenDetected() {
+				/**
-					m_writeErrorWhenDetexted=true;
+				 * @brief Set the display of the error when detected.
+				 * @param[in] _value true: display error, false not display error (get it at end)
+				 */
+				void setDisplayError(bool _value) {
+					m_writeErrorWhenDetexted = _value;
 				};
-				void notDisplayErrorWhenDetected() {
+				/**
-					m_writeErrorWhenDetexted=false;
+				 * @brief Get the display of the error status.
-				};
+				 * @return true Display error
-				
+				 * @return false Does not display error (get it at end)
-				void createError(const std::string& _data, size_t _pos, const ejson::FilePos& _filePos, const std::string& _comment);
+				 */
+				bool getDisplayError();
+				/**
+				 * @brief Display error detected.
+				 */
 				void displayError();
+				/**
+				 * @brief When parsing a subParser create an error that might be write later
+				 * @param[in] _data Wall File or stream
+				 * @param[in] _pos Position in the file (in nb char)
+				 * @param[in] _filePos Position in x/y in the file
+				 * @param[in] _comment Help coment
+				 */
+				void createError(const std::string& _data,
+				                 size_t _pos,
+				                 const ejson::FilePos& _filePos,
+				                 const std::string& _comment);
 			public:
-				bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override;
+				bool iParse(const std::string& _data,
+				            size_t& _pos,
+				            ejson::FilePos& _filePos,
+				            ejson::internal::Document& _doc) override;
 				bool iGenerate(std::string& _data, size_t _indent) const override;
 		};
 	}
 }
 
+/**
+ * @brief Automatic create error on the basic Document object
+ * @param[in] doc Document reference
+ * @param[in] data main string parsed
+ * @param[in] pos Position in the file
+ * @param[in] filePos position in linre row in the file
+ * @param[in] comment Comment of the error find
+ */
 #define EJSON_CREATE_ERROR(doc,data,pos,filePos,comment) \
 	do { \
 		EJSON_ERROR(comment); \

ejson/internal/Null.h

@@ -12,6 +12,9 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Null internal data implementation.
+		 */
 		class Null : public ejson::internal::Value {
 			protected:
 				/**
@@ -19,6 +22,10 @@ namespace ejson {
 				 */
 				Null();
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::Null
+				 * @return A SharedPtr on the Null value
+				 */
 				static ememory::SharedPtr<Null> create();
 			public:
 				bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override;

ejson/internal/Number.h

@@ -12,13 +12,22 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Number internal data implementation.
+		 */
 		class Number : public ejson::internal::Value {
 			protected:
 				/**
 				 * @brief basic element of a xml structure
+				 * @param[in] _value Value to set on the ejson::Value
 				 */
 				Number(double _value=0.0);
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::Number
+				 * @param[in] _value Value to set on the ejson::Value
+				 * @return A SharedPtr on the Number value
+				 */
 				static ememory::SharedPtr<Number> create(double _value=0.0);
 			protected:
 				double m_value; //!< value of the node

ejson/internal/Object.h

@@ -14,6 +14,9 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson Object internal data implementation.
+		 */
 		class Object : public ejson::internal::Value {
 			protected:
 				/**
@@ -23,7 +26,16 @@ namespace ejson {
 					m_type = ejson::valueType::object;
 				};
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::Object
+				 * @return A SharedPtr on the Object value
+				 */
 				static ememory::SharedPtr<Object> create();
+				/**
+				 * @brief Create factory on the ejson::internal::Object
+				 * @param[in] _data Json stream to parse and interprete
+				 * @return A SharedPtr on the Object value
+				 */
 				static ememory::SharedPtr<Object> create(const std::string& _data);
 			protected:
 				etk::Hash<ememory::SharedPtr<ejson::internal::Value> > m_value; //!< value of the node (for element this is the name, for text it is the inside text ...)
@@ -40,7 +52,11 @@ namespace ejson {
 				 * @return pointer on the element requested or nullptr if it not the corect type or does not existed
 				 */
 				ememory::SharedPtr<ejson::internal::Value> get(const std::string& _name);
-				//! @previous
+				/**
+				 * @brief get the sub element with his name (no cast check)
+				 * @param[in] _name name of the object
+				 * @return pointer on the element requested or nullptr if it not the corect type or does not existed
+				 */
 				const ememory::SharedPtr<const ejson::internal::Value> get(const std::string& _name) const;
 			public:
 				/**
@@ -89,16 +105,23 @@ namespace ejson {
 				 * @param[in] _id Id of the element.
 				 */
 				void remove(size_t _id);
+				/**
+				 * @brief Clone the current object in an other Object
+				 * @param[in] _obj Other object ot overwride
+				 * @return true The clone has been corectly done, false otherwise
+				 */
+				bool cloneIn(const ememory::SharedPtr<ejson::internal::Object>& _obj) const;
+				/**
+				 * @brief Clone the current object
+				 * @return A new object that has been clone
+				 */
+				ememory::SharedPtr<ejson::internal::Object> cloneObj() const;
 			public:
 				bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override;
 				bool iGenerate(std::string& _data, size_t _indent) const override;
 				void clear() override;
 				bool transfertIn(ememory::SharedPtr<ejson::internal::Value> _obj) override;
 				ememory::SharedPtr<ejson::internal::Value> clone() const override;
-				
-				
-				bool cloneIn(const ememory::SharedPtr<ejson::internal::Object>& _obj) const;
-				ememory::SharedPtr<ejson::internal::Object> cloneObj() const;
 		};
 	}
 }

ejson/internal/String.h

@@ -12,13 +12,22 @@
 
 namespace ejson {
 	namespace internal {
+		/**
+		 * @brief ejson String internal data implementation.
+		 */
 		class String : public ejson::internal::Value {
 			protected:
 				/**
 				 * @brief basic element of a xml structure
+				 * @param[in] _value Value to set on the ejson::Value
 				 */
 				String(const std::string& _value="");
 			public:
+				/**
+				 * @brief Create factory on the ejson::internal::String
+				 * @param[in] _value Value to set on the ejson::Value
+				 * @return A SharedPtr on the String value
+				 */
 				static ememory::SharedPtr<String> create(const std::string& _value="");
 			protected:
 				std::string m_value; //!< value of the node (for element this is the name, for text it is the inside text ...)

ejson/internal/Value.h

@@ -27,6 +27,9 @@ namespace ejson {
 	#else
 		#define EJSON_PARSE_ATTRIBUTE EJSON_DEBUG
 	#endif
+	/**
+	 * @brief ejson internal data implementation (not for external user).
+	 */
 	namespace internal {
 		class Document;
 		class Array;
@@ -36,7 +39,7 @@ namespace ejson {
 		class Number;
 		class String;
 		/**
-		 * @brief Basic main object of all json elements.
+		 * @brief Basic main object of all json data.
 		 */
 		class Value : public ememory::EnableSharedFromThis<Value> {
 			protected: