Documentation issues

[lhunath]

json_object.h
Error:(333, 11) parameter 'jso' not found in the function declaration
Error:(334, 11) parameter 'userdata' not found in the function declaration
Error:(342, 11) parameter 'jso' not found in the function declaration
Error:(343, 11) parameter 'pb' not found in the function declaration
Error:(344, 11) parameter 'level' not found in the function declaration
Error:(345, 11) parameter 'flags' not found in the function declaration
Error:(434, 5) declaration is marked with '\deprecated' command but does not have a deprecation attribute
Note:(437, 24) add a deprecation attribute to the declaration to silence this warning
Error:(548, 10) parameter 'obj' not found in the function declaration
Note:(548, 10) did you mean 'jso'?

linkhash.h
Error:(305, 5) declaration is marked with '\deprecated' command but does not have a deprecation attribute
Note:(311, 35) add a deprecation attribute to the declaration to silence this warning

[lhunath]

The annoying thing about this is that the issues are in the .h files and as a result, it inhibits every client app from building with the -Werror -Wdocumentation flags.

[lhunath]

diff -ru ./json_object.h libjson-c-osx/include/json-c/json_object.h
--- ./json_object.h	2017-07-27 22:24:07.000000000 -0400
+++ libjson-c-osx/include/json-c/json_object.h	2017-08-12 21:52:28.000000000 -0400
@@ -329,20 +329,12 @@
 /**
  * Simply call free on the userdata pointer.
  * Can be used with json_object_set_serializer().
- *
- * @param jso unused
- * @param userdata the pointer that is passed to free().
  */
 json_object_delete_fn json_object_free_userdata;
 
 /**
  * Copy the jso->_userdata string over to pb as-is.
  * Can be used with json_object_set_serializer().
- *
- * @param jso The object whose _userdata is used.
- * @param pb The destination buffer.
- * @param level Ignored.
- * @param flags Ignored.
  */
 json_object_to_json_string_fn json_object_userdata_to_json_string;
 
@@ -434,7 +426,7 @@
  * @deprecated Please use json_object_object_get_ex
  */
 JSON_EXPORT struct json_object* json_object_object_get(const struct json_object* obj,
-						  const char *key);
+						  const char *key) __deprecated;
 
 /** Get the json_object associated with a given object field.
  *
@@ -545,7 +537,7 @@
 * Pointers to the json_object pointers will be passed as the two arguments
 * to @sort_fn
 *
-* @param obj the json_object instance
+* @param jso the json_object instance
 * @param sort_fn a sorting function
 */
 JSON_EXPORT void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *));
diff -ru ./linkhash.h libjson-c-osx/include/json-c/linkhash.h
--- ./linkhash.h	2017-07-27 22:24:07.000000000 -0400
+++ libjson-c-osx/include/json-c/linkhash.h	2017-08-12 21:52:08.000000000 -0400
@@ -308,7 +308,7 @@
  * 	However, because its interface is public, it will remain part of
  * 	the API on the off chance of legacy software using it externally.
  */
-void lh_abort(const char *msg, ...);
+void lh_abort(const char *msg, ...) __deprecated;
 
 /**
  * Resizes the specified table.
@@ -340,7 +340,7 @@
 /* Don't use this outside of linkhash.h: */
 #ifdef __UNCONST
 #define _LH_UNCONST(a) __UNCONST(a)
-#else
+#else
 #define _LH_UNCONST(a) ((void *)(uintptr_t)(const void *)(a))
 #endif
 

[hawicz]

1: This adds a "__deprecated" qualifier, which is unlikely to work widely, and even if it does work, I expect it would re-introduce warnings that we don't actually want (i.e. by popular demand json_object_object_get isn't really deprecated, just discouraged).
2: it drops useful documentation. Instead, I'm going to add some pragma's to disable the warnings in this file.
Note that the warnings are wrong about the "parameter ... not found in the function declaration" bits: the parameters are there, in the typedef, but your compiler isn't following that indirection.

[hawicz]

See commits 4ac47a0 and edde8ef