From 067c8a9527be15688db798aa3736129a31241a82 Mon Sep 17 00:00:00 2001 From: Ghislain MARY Date: Thu, 14 Aug 2014 14:44:59 +0200 Subject: [PATCH] For functions returning or taking an MSList as an argument, specify what the MSList contains in the documentation. --- coreapi/authentication.c | 2 ++ coreapi/chat.c | 4 ++-- coreapi/help/Doxyfile.in | 2 +- coreapi/linphonecore.c | 14 ++++++++++++++ coreapi/linphonefriend.h | 3 ++- coreapi/proxy.c | 2 ++ tools/genapixml.py | 15 +++++++++++++++ tools/python/apixml2python.py | 3 ++- 8 files changed, 40 insertions(+), 5 deletions(-) diff --git a/coreapi/authentication.c b/coreapi/authentication.c index 59b3ea1b5..de7248316 100644 --- a/coreapi/authentication.c +++ b/coreapi/authentication.c @@ -378,6 +378,8 @@ void linphone_core_remove_auth_info(LinphoneCore *lc, const LinphoneAuthInfo *in /** * Returns an unmodifiable list of currently entered LinphoneAuthInfo. + * @param[in] lc The LinphoneCore object + * @return \mslist{LinphoneAuthInfo} **/ const MSList *linphone_core_get_auth_info_list(const LinphoneCore *lc){ return lc->auth_info; diff --git a/coreapi/chat.c b/coreapi/chat.c index c9ec8b6d5..66bde2968 100644 --- a/coreapi/chat.c +++ b/coreapi/chat.c @@ -246,8 +246,8 @@ bool_t linphone_core_chat_enabled(const LinphoneCore *lc){ /** * Returns an list of chat rooms - * @param lc #LinphoneCore object - * @return A list of #LinphoneChatRoom + * @param[in] lc #LinphoneCore object + * @return \mslist{LinphoneChatRoom} **/ MSList* linphone_core_get_chat_rooms(LinphoneCore *lc) { return lc->chatrooms; diff --git a/coreapi/help/Doxyfile.in b/coreapi/help/Doxyfile.in index 27068c53d..12facea9b 100644 --- a/coreapi/help/Doxyfile.in +++ b/coreapi/help/Doxyfile.in @@ -34,7 +34,7 @@ DETAILS_AT_TOP = NO INHERIT_DOCS = YES DISTRIBUTE_GROUP_DOC = NO TAB_SIZE = 8 -ALIASES = +ALIASES = mslist{1}="A list of \ref \1 objects. \xmlonly \1 \endxmlonly" OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO SUBGROUPING = YES diff --git a/coreapi/linphonecore.c b/coreapi/linphonecore.c index 59c46fee2..34add6e0f 100644 --- a/coreapi/linphonecore.c +++ b/coreapi/linphonecore.c @@ -1466,6 +1466,8 @@ LinphoneCore *linphone_core_new_with_config(const LinphoneCoreVTable *vtable, st /** * Returns the list of available audio codecs. + * @param[in] lc The LinphoneCore object + * @return \mslist{PayloadType} * * This list is unmodifiable. The ->data field of the MSList points a PayloadType * structure holding the codec information. @@ -1480,6 +1482,8 @@ const MSList *linphone_core_get_audio_codecs(const LinphoneCore *lc) /** * Returns the list of available video codecs. + * @param[in] lc The LinphoneCore object + * @return \mslist{PayloadType} * * This list is unmodifiable. The ->data field of the MSList points a PayloadType * structure holding the codec information. @@ -1631,6 +1635,9 @@ LinphoneAddress *linphone_core_get_primary_contact_parsed(LinphoneCore *lc){ /** * Sets the list of audio codecs. + * @param[in] lc The LinphoneCore object + * @param[in] codecs \mslist{PayloadType} + * @return 0 * * @ingroup media_parameters * The list is taken by the LinphoneCore thus the application should not free it. @@ -1646,6 +1653,9 @@ int linphone_core_set_audio_codecs(LinphoneCore *lc, MSList *codecs) /** * Sets the list of video codecs. + * @param[in] lc The LinphoneCore object + * @param[in] codecs \mslist{PayloadType} + * @return 0 * * @ingroup media_parameters * The list is taken by the LinphoneCore thus the application should not free it. @@ -3672,6 +3682,8 @@ int linphone_core_terminate_all_calls(LinphoneCore *lc){ /** * Returns the current list of calls. + * @param[in] lc The LinphoneCore object + * @return \mslist{LinphoneCall} * * Note that this list is read-only and might be changed by the core after a function call to linphone_core_iterate(). * Similarly the LinphoneCall objects inside it might be destroyed without prior notice. @@ -4814,6 +4826,8 @@ LinphoneFirewallPolicy linphone_core_get_firewall_policy(const LinphoneCore *lc) /** * Get the list of call logs (past calls). + * @param[in] lc The LinphoneCore object + * @return \mslist{LinphoneCallLog} * * @ingroup call_logs **/ diff --git a/coreapi/linphonefriend.h b/coreapi/linphonefriend.h index 891bf7631..f64286c0e 100644 --- a/coreapi/linphonefriend.h +++ b/coreapi/linphonefriend.h @@ -356,7 +356,8 @@ LINPHONE_PUBLIC void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneF /** * Get Buddy list of LinphoneFriend - * @param lc #LinphoneCore object + * @param[in] lc #LinphoneCore object + * @return \mslist{LinphoneFriend} */ LINPHONE_PUBLIC const MSList * linphone_core_get_friend_list(const LinphoneCore *lc); diff --git a/coreapi/proxy.c b/coreapi/proxy.c index e6a33d556..d66dd30fd 100644 --- a/coreapi/proxy.c +++ b/coreapi/proxy.c @@ -1198,6 +1198,8 @@ int linphone_core_get_default_proxy(LinphoneCore *lc, LinphoneProxyConfig **conf /** * Returns an unmodifiable list of entered proxy configurations. + * @param[in] lc The LinphoneCore object + * @return \mslist{LinphoneProxyConfig} **/ const MSList *linphone_core_get_proxy_config_list(const LinphoneCore *lc){ return lc->sip_conf.proxies; diff --git a/tools/genapixml.py b/tools/genapixml.py index 2c9286792..4f834fb0c 100755 --- a/tools/genapixml.py +++ b/tools/genapixml.py @@ -72,6 +72,7 @@ class CArgument(CObject): def __init__(self, t, name = '', enums = [], structs = []): CObject.__init__(self, name) self.description = None + self.containedType = None keywords = [ 'const', 'struct', 'enum', 'signed', 'unsigned', 'short', 'long', '*' ] fullySplittedType = [] splittedType = t.strip().split(' ') @@ -302,6 +303,8 @@ class Project: para.remove(n) for n in para.findall('.//ref'): n.attrib = {} + for n in para.findall(".//mslist"): + para.remove(n) if descriptionNode.tag == 'parameterdescription': descriptionNode.tag = 'description' if descriptionNode.tag == 'simplesect': @@ -485,6 +488,10 @@ class Project: returnarg = CArgument(t, enums = self.enums, structs = self.__structs) returndesc = node.find("./detaileddescription/para/simplesect[@kind='return']") if returndesc is not None: + if returnarg.ctype == 'MSList': + n = returndesc.find('.//mslist') + if n is not None: + returnarg.containedType = n.text returnarg.description = self.__cleanDescription(returndesc) elif returnarg.completeType != 'void': missingDocWarning += "\tReturn value is not documented\n" @@ -504,6 +511,10 @@ class Project: for arg in argslist.arguments: for paramdesc in paramdescs: if arg.name == paramdesc.find('./parameternamelist').find('./parametername').text: + if arg.ctype == 'MSList': + n = paramdesc.find('.//mslist') + if n is not None: + arg.containedType = n.text arg.description = self.__cleanDescription(paramdesc.find('./parameterdescription')) missingDocWarning = '' for arg in argslist.arguments: @@ -594,12 +605,16 @@ class Generator: functionAttributes['location'] = f.location functionNode = ET.SubElement(parentNode, nodeName, functionAttributes) returnValueAttributes = { 'type' : f.returnArgument.ctype, 'completetype' : f.returnArgument.completeType } + if f.returnArgument.containedType is not None: + returnValueAttributes['containedtype'] = f.returnArgument.containedType returnValueNode = ET.SubElement(functionNode, 'return', returnValueAttributes) if f.returnArgument.description is not None: returnValueNode.append(f.returnArgument.description) argumentsNode = ET.SubElement(functionNode, 'arguments') for arg in f.arguments: argumentNodeAttributes = { 'name' : arg.name, 'type' : arg.ctype, 'completetype' : arg.completeType } + if arg.containedType is not None: + argumentNodeAttributes['containedtype'] = arg.containedType argumentNode = ET.SubElement(argumentsNode, 'argument', argumentNodeAttributes) if arg.description is not None: argumentNode.append(arg.description) diff --git a/tools/python/apixml2python.py b/tools/python/apixml2python.py index dd37e2027..79b2bae0b 100755 --- a/tools/python/apixml2python.py +++ b/tools/python/apixml2python.py @@ -67,11 +67,12 @@ blacklisted_functions = [ 'linphone_core_get_video_port_range', # to be handwritten because of result via arguments 'linphone_core_publish', # missing LinphoneContent 'linphone_core_serialize_logs', # There is no use to wrap this function + 'linphone_core_set_audio_codecs', # missing PayloadType and MSList 'linphone_core_set_log_file', # There is no use to wrap this function 'linphone_core_set_log_handler', # Hand-written but put directly in the linphone module 'linphone_core_set_log_level', # There is no use to wrap this function + 'linphone_core_set_video_codecs', # missing PayloadType and MSList 'linphone_core_set_video_policy', # missing LinphoneVideoPolicy - 'linphone_core_set_audio_codecs', # missing PayloadType and MSList 'linphone_core_set_sip_transports', # missing LCSipTransports 'linphone_core_subscribe', # missing LinphoneContent 'linphone_event_notify', # missing LinphoneContent