Merge pull request #25 from kdopen/doc_cleanup

Clean up documentation and correct sample code

json_object_iterator.c

@@ -1,17 +1,17 @@
-/** 
+/**
 *******************************************************************************
-* @file cjson_object_iterator.c
-* 
-* Copyright (c) 2009 Hewlett-Packard Development Company, L.P.
+* @file json_object_iterator.c
+*
+* Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the MIT license. See COPYING for details.
 *
-* @brief  cjson forces clients to use its private data
+* @brief  json-c forces clients to use its private data
 *         structures for JSON Object iteration.  This API
 *         implementation corrects that by abstracting the
-*         private cjson details.
-* 
+*         private json-c details.
+*
 *******************************************************************************
 */
 
@@ -25,30 +25,30 @@
 
 /**
  * How It Works
- * 
- * For each JSON Object, cjson maintains a linked list of zero
+ *
+ * For each JSON Object, json-c maintains a linked list of zero
  * or more lh_entry (link-hash entry) structures inside the
  * Object's link-hash table (lh_table).
- * 
+ *
  * Each lh_entry structure on the JSON Object's linked list
  * represents a single name/value pair.  The "next" field of the
  * last lh_entry in the list is set to NULL, which terminates
  * the list.
- * 
+ *
  * We represent a valid iterator that refers to an actual
  * name/value pair via a pointer to the pair's lh_entry
  * structure set as the iterator's opaque_ field.
- * 
- * We follow cjson's current pair list representation by
+ *
+ * We follow json-c's current pair list representation by
  * representing a valid "end" iterator (one that refers past the
  * last pair) with a NULL value in the iterator's opaque_ field.
- * 
+ *
  * A JSON Object without any pairs in it will have the "head"
  * field of its lh_table structure set to NULL.  For such an
  * object, json_object_iter_begin will return an iterator with
  * the opaque_ field set to NULL, which is equivalent to the
  * "end" iterator.
- * 
+ *
  * When iterating, we simply update the iterator's opaque_ field
  * to point to the next lh_entry structure in the linked list.
  * opaque_ will become NULL once we iterate past the last pair
@@ -57,7 +57,7 @@
  */
 
 /// Our current representation of the "end" iterator;
-/// 
+///
 /// @note May not always be NULL
 static const void* kObjectEndIterValue = NULL;
 

json_object_iterator.h

@@ -1,26 +1,21 @@
-/** 
+/**
 *******************************************************************************
 * @file json_object_iterator.h
-* 
-* Copyright (c) 2009 Hewlett-Packard Development Company, L.P.
+*
+* Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the MIT license. See COPYING for details.
-* 
-* @brief  cjson forces clients to use its private data
+*
+* @brief  json-c forces clients to use its private data
 *         structures for JSON Object iteration.  This API
-*         corrects that by abstracting the private cjson
+*         corrects that by abstracting the private json-c
 *         details.
-* 
-*         The intention is to add this API (and its
-*         implementation) to Palm's version of the cjson
-*         library, at which point it can be removed from the
-*         Wireless System Framework library implementation.
-* 
-* API attributes:
-*   * Thread-safe: NO
-*   * Re-entrant: NO
-* 
+*
+* API attributes: <br>
+*   * Thread-safe: NO<br>
+*   * Reentrant: NO
+*
 *******************************************************************************
 */
 
@@ -31,7 +26,7 @@
 #include <stddef.h>
 #include <stdbool.h>
 
-#ifdef __cplusplus 
+#ifdef __cplusplus
 extern "C" {
 #endif
 
@@ -42,7 +37,7 @@ struct json_object_iter_info_;
 
 /**
  * The opaque iterator that references a name/value pair within
- * a JSON Object intance or the "end" iterator value.
+ * a JSON Object instance or the "end" iterator value.
  */
 struct json_object_iterator {
     const void* opaque_;
@@ -50,7 +45,7 @@ struct json_object_iterator {
 
 
 /**
- * forward declaration of cjson's JSON value instance structure
+ * forward declaration of json-c's JSON value instance structure
  */
 struct json_object;
 
@@ -60,33 +55,32 @@ struct json_object;
  * is convenient for initializing an iterator variable to a
  * default state (e.g., initialization list in a class'
  * constructor).
- * 
- * @code 
+ *
+ * @code
  * struct json_object_iterator iter = json_object_iter_init_default();
  * MyClass() : iter_(json_object_iter_init_default())
  * @endcode
- * 
+ *
  * @note The initialized value doesn't reference any specific
  *       pair, is considered an invalid iterator, and MUST NOT
- *       be passed to any cjson API that expects a valid
+ *       be passed to any json-c API that expects a valid
  *       iterator.
- * 
+ *
  * @note User and internal code MUST NOT make any assumptions
  *       about and dependencies on the value of the "default"
  *       iterator value.
- * 
+ *
  * @return json_object_iterator
  */
 struct json_object_iterator
 json_object_iter_init_default(void);
 
 /** Retrieves an iterator to the first pair of the JSON Object.
- * 
- * @note WARNING: Any modification of the underlying pair
- *       invalidates all iterators to that pair.
- * 
- * @param obj JSON Object instance (MUST be of type
- *             json_type_object)
+ *
+ * @warning 	Any modification of the underlying pair invalidates all
+ * 		iterators to that pair.
+ *
+ * @param obj	JSON Object instance (MUST be of type json_object)
  *
  * @return json_object_iterator If the JSON Object has at
  *              least one pair, on return, the iterator refers
@@ -94,29 +88,22 @@ json_object_iter_init_default(void);
  *              have any pairs, the returned iterator is
  *              equivalent to the "end" iterator for the same
  *              JSON Object instance.
- * 
- * @code    
+ *
+ * @code
  * struct json_object_iterator it;
  * struct json_object_iterator itEnd;
- * struct json_object* obj = json_tokener_parse(
- *        "{'first':'george', 'age':100}");
- * json_object_iter_begin(obj, &it);
- * json_object_iter_end(obj, &itEnd);
+ * struct json_object* obj;
+ *
+ * obj = json_tokener_parse("{'first':'george', 'age':100}");
+ * it = json_object_iter_begin(obj);
+ * itEnd = json_object_iter_end(obj);
+ *
  * while (!json_object_iter_equal(&it, &itEnd)) {
  *     printf("%s\n",
  *            json_object_iter_peek_name(&it));
  *     json_object_iter_next(&it);
  * }
  *
- * struct json_object* obj = json_tokener_parse(
- *        "{'first':'george', 'age':100}");
- * struct json_object_iterator it;
- * bool iterable = json_object_iter_begin(&it);
- * if (iterable) {
- *     do  {
- *         printf("%s\n", json_object_iter_peek_name(&it));
- *     } while (json_object_iter_next(&it));
- * }
  * @endcode
  */
 struct json_object_iterator
@@ -124,11 +111,11 @@ json_object_iter_begin(struct json_object* obj);
 
 /** Retrieves the iterator that represents the position beyond the
  *  last pair of the given JSON Object instance.
- * 
- *  @note WARNING: Do NOT write code that assumes that the "end"
+ *
+ *  @warning Do NOT write code that assumes that the "end"
  *        iterator value is NULL, even if it is so in a
  *        particular instance of the implementation.
- * 
+ *
  *  @note The reason we do not (and MUST NOT) provide
  *        "json_object_iter_is_end(json_object_iterator* iter)"
  *        type of API is because it would limit the underlying
@@ -140,11 +127,10 @@ json_object_iter_begin(struct json_object* obj);
  *        representation without burdening the iterator
  *        structure with unnecessary data.
  *
- *  @note For performance reasons, memoize the "end" iterator prior
+ *  @note For performance reasons, memorize the "end" iterator prior
  *        to any loop.
- * 
- * @param obj JSON Object instance (MUST be of type
- *             json_type_object)
+ *
+ * @param obj JSON Object instance (MUST be of type json_object)
  *
  * @return json_object_iterator On return, the iterator refers
  *              to the "end" of the Object instance's pairs
@@ -155,12 +141,10 @@ struct json_object_iterator
 json_object_iter_end(const struct json_object* obj);
 
 /** Returns an iterator to the next pair, if any
- * 
- * @note WARNING: Any modification of the underlying pair
- *       invalidates all iterators to that pair.
- * 
- * @param iter Iterator that references a name/value pair; 
- * 
+ *
+ * @warning	Any modification of the underlying pair
+ *       	invalidates all iterators to that pair.
+ *
  * @param iter [IN/OUT] Pointer to iterator that references a
  *         name/value pair; MUST be a valid, non-end iterator.
  *         WARNING: bad things will happen if invalid or "end"
@@ -177,13 +161,14 @@ json_object_iter_next(struct json_object_iterator* iter);
 
 /** Returns a const pointer to the name of the pair referenced
  *  by the given iterator.
- * 
+ *
  * @param iter pointer to iterator that references a name/value
  *             pair; MUST be a valid, non-end iterator.
- *             WARNING: bad things will happen if invalid or
- *             "end" iterator is passed.
- * 
- * @return const char* Pointer to the name of the rerferenced
+ *
+ * @warning	bad things will happen if an invalid or
+ *             	"end" iterator is passed.
+ *
+ * @return const char* Pointer to the name of the referenced
  *         name/value pair.  The name memory belongs to the
  *         name/value pair, will be freed when the pair is
  *         deleted or modified, and MUST NOT be modified or
@@ -193,21 +178,22 @@ const char*
 json_object_iter_peek_name(const struct json_object_iterator* iter);
 
 
-/** Returns a pointer to the cjson instance representing the
+/** Returns a pointer to the json-c instance representing the
  *  value of the referenced name/value pair, without altering
  *  the instance's reference count.
- * 
- * @param iter pointer to iterator that references a name/value
- *             pair; MUST be a valid, non-end iterator.
- *             WARNING: bad things will happen if invalid or
+ *
+ * @param iter 	pointer to iterator that references a name/value
+ *             	pair; MUST be a valid, non-end iterator.
+ *
+ * @warning	bad things will happen if invalid or
  *             "end" iterator is passed.
- * 
- * @return struct json_object* Pointer to the cjson value
+ *
+ * @return struct json_object* Pointer to the json-c value
  *         instance of the referenced name/value pair;  the
  *         value's reference count is not changed by this
- *         function: if you plan to hold on to this cjson node,
+ *         function: if you plan to hold on to this json-c node,
  *         take a look at json_object_get() and
- *         json_object_put(). IMPORTANT: cjson API represents
+ *         json_object_put(). IMPORTANT: json-c API represents
  *         the JSON Null value as a NULL json_object instance
  *         pointer.
  */
@@ -219,7 +205,7 @@ json_object_iter_peek_value(const struct json_object_iterator* iter);
  *  for end of iteration by comparing an iterator to the
  *  corresponding "end" iterator (that was derived from the same
  *  JSON Object instance).
- * 
+ *
  *  @note The reason we do not (and MUST NOT) provide
  *        "json_object_iter_is_end(json_object_iterator* iter)"
  *        type of API is because it would limit the underlying
@@ -228,15 +214,15 @@ json_object_iter_peek_value(const struct json_object_iterator* iter);
  *        the iterator structure). The equality test method, on
  *        the other hand, permits us to cleanly abstract pretty
  *        much any reasonable underlying representation.
- * 
+ *
  * @param iter1 Pointer to first valid, non-NULL iterator
  * @param iter2 POinter to second valid, non-NULL iterator
- * 
- * @note WARNING: if a NULL iterator pointer or an uninitialized
- *       or invalid iterator, or iterators derived from
- *       different JSON Object instances are passed, bad things
- *       will happen!
- * 
+ *
+ * @warning	if a NULL iterator pointer or an uninitialized
+ *       	or invalid iterator, or iterators derived from
+ *       	different JSON Object instances are passed, bad things
+ *       	will happen!
+ *
  * @return bool non-zero if iterators are equal (i.e., both
  *         reference the same name/value pair or are both at
  *         "end"); zero if they are not equal.