diff options
author | Keith Derrick <keith.derrick@palm.com> | 2012-04-23 15:34:44 -0700 |
---|---|---|
committer | Keith Derrick <keith.derrick@palm.com> | 2012-04-23 15:34:44 -0700 |
commit | ded667a6126f0a97146d2a4e88693a6e9bae191c (patch) | |
tree | 179ff9d8d8330e010bbf1ca2e0a831163773f7fc | |
parent | 178a4b059cee947832c6ff2c531876dba56851e9 (diff) | |
download | json-c-ded667a6126f0a97146d2a4e88693a6e9bae191c.tar.gz |
Clean up documentation and correct sample code
-rw-r--r-- | json_object_iterator.c | 32 | ||||
-rw-r--r-- | json_object_iterator.h | 148 |
2 files changed, 83 insertions, 97 deletions
diff --git a/json_object_iterator.c b/json_object_iterator.c index b887eb2..7191b53 100644 --- a/json_object_iterator.c +++ b/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; diff --git a/json_object_iterator.h b/json_object_iterator.h index 21feaf5..3221a15 100644 --- a/json_object_iterator.h +++ b/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. |