more documentation

Doxyfile

@@ -83,7 +83,7 @@ GENERATE_DEPRECATEDLIST= YES
 ENABLED_SECTIONS       =
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = NO
-SHOW_FILES             = YES
+SHOW_FILES             = NO
 SHOW_NAMESPACES        = NO
 FILE_VERSION_FILTER    =
 LAYOUT_FILE            =
@@ -153,11 +153,11 @@ HTML_COLORSTYLE_GAMMA  = 80
 HTML_TIMESTAMP         = YES
 HTML_DYNAMIC_SECTIONS  = NO
 HTML_INDEX_NUM_ENTRIES = 100
-GENERATE_DOCSET        = NO
+GENERATE_DOCSET        = YES
 DOCSET_FEEDNAME        = "Doxygen generated docs"
 DOCSET_BUNDLE_ID       = me.nlohmann.json
 DOCSET_PUBLISHER_ID    = me.nlohmann
-DOCSET_PUBLISHER_NAME  = Publisher
+DOCSET_PUBLISHER_NAME  = Niels Lohmann
 GENERATE_HTMLHELP      = NO
 CHM_FILE               =
 HHC_LOCATION           =

Makefile

@@ -15,6 +15,24 @@ clean:
 json_unit: test/unit.cpp src/json.hpp test/catch.hpp
 	$(CXX) -std=c++11 $(CXXFLAGS) $(FLAGS) $(CPPFLAGS) -I src -I test $< $(LDFLAGS) -o $@
 
+check: json_unit
+	./json_unit "*"
+	make check -C docs/examples
+
+docset:
+	cp Doxyfile Doxyfile_docset
+	gsed -i 's/DISABLE_INDEX          = NO/DISABLE_INDEX          = YES/' Doxyfile_docset
+	gsed -i 's/SEARCHENGINE           = YES/SEARCHENGINE           = NO/' Doxyfile_docset
+	gsed -i 's/GENERATE_TREEVIEW      = YES/GENERATE_TREEVIEW      = NO/' Doxyfile_docset
+	gsed -i 's/SEPARATE_MEMBER_PAGES  = NO/SEPARATE_MEMBER_PAGES  = YES/' Doxyfile_docset
+	gsed -i 's/BINARY_TOC             = YES/BINARY_TOC             = NO/' Doxyfile_docset
+	rm -fr html *.docset
+	doxygen Doxyfile_docset
+	make -C html
+	mv html/*.docset .
+	gsed -i 's@<string>doxygen</string>@<string>json</string>@' me.nlohmann.json.docset/Contents/Info.plist
+	rm -fr Doxyfile_docset html
+
 # create scanner with re2c
 re2c: src/json.hpp.re2c
 	$(RE2C) -b -s -i --no-generation-date $< | $(SED) '1d' > src/json.hpp

docs/examples/back.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_null;
+    json j_boolean = true;
+    json j_number_integer = 17;
+    json j_number_float = 23.42;
+    json j_object = {{"one", 1}, {"two", 2}};
+    json j_object_empty(json::value_t::object);
+    json j_array = {1, 2, 4, 8, 16};
+    json j_array_empty(json::value_t::array);
+    json j_string = "Hello, world";
+
+    // call back()
+    //std::cout << j_null.back() << '\n';          // would throw
+    std::cout << j_boolean.back() << '\n';
+    std::cout << j_number_integer.back() << '\n';
+    std::cout << j_number_float.back() << '\n';
+    std::cout << j_object.back() << '\n';
+    //std::cout << j_object_empty.back() << '\n';  // would throw
+    std::cout << j_array.back() << '\n';
+    //std::cout << j_array_empty.back() << '\n';   // would throw
+    std::cout << j_string.back() << '\n';
+}

docs/examples/back.output

+true
+17
+23.42
+2
+16
+"Hello, world"

docs/examples/front.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_null;
+    json j_boolean = true;
+    json j_number_integer = 17;
+    json j_number_float = 23.42;
+    json j_object = {{"one", 1}, {"two", 2}};
+    json j_object_empty(json::value_t::object);
+    json j_array = {1, 2, 4, 8, 16};
+    json j_array_empty(json::value_t::array);
+    json j_string = "Hello, world";
+
+    // call front()
+    //std::cout << j_null.front() << '\n';          // would throw
+    std::cout << j_boolean.front() << '\n';
+    std::cout << j_number_integer.front() << '\n';
+    std::cout << j_number_float.front() << '\n';
+    std::cout << j_object.front() << '\n';
+    //std::cout << j_object_empty.front() << '\n';  // would throw
+    std::cout << j_array.front() << '\n';
+    //std::cout << j_array_empty.front() << '\n';   // would throw
+    std::cout << j_string.front() << '\n';
+}

docs/examples/front.output

+true
+17
+23.42
+1
+1
+"Hello, world"

src/json.hpp.re2c

@@ -1548,19 +1548,56 @@ class basic_json
         return m_value.object->operator[](key);
     }
 
-    /// access the first element
+    /*!
+    @brief access the first element
+
+    Returns a reference to the first element in the container. For a JSON
+    container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
+
+    @return In case of a compound value (array or object), a reference to the
+    first element is returned. In cast of number, string, or boolean values, a
+    reference to the value is returned.
+
+    @complexity Constant.
+
+    @note Calling `front` on an empty container is undefined.
+
+    @throw std::out_of_range when called on null value.
+
+    @liveexample{The following code shows an example for @ref front.,front}
+    */
     reference front()
     {
         return *begin();
     }
 
-    /// access the first element
+    /*!
+    @copydoc basic_json::front()
+    */
     const_reference front() const
     {
         return *cbegin();
     }
 
-    /// access the last element
+    /*!
+    @brief access the last element
+
+    Returns a reference to the last element in the container. For a JSON
+    container `c`, the expression `c.back()` is equivalent to `{ auto tmp =
+    c.end(); --tmp; return *tmp; }`.
+
+    @return In case of a compound value (array or object), a reference to the
+    last element is returned. In cast of number, string, or boolean values, a
+    reference to the value is returned.
+
+    @complexity Constant.
+
+    @note Calling `back` on an empty container is undefined.
+
+    @throw std::out_of_range when called on null value.
+
+    @liveexample{The following code shows an example for @ref back.,back}
+    */
     reference back()
     {
         auto tmp = end();
@@ -1568,7 +1605,9 @@ class basic_json
         return *tmp;
     }
 
-    /// access the last element
+    /*!
+    @copydoc basic_json::back()
+    */
     const_reference back() const
     {
         auto tmp = cend();