From 7d014575516c6c2fd81b63bd85cd5b2746109260 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 26 Apr 2018 18:35:03 -0700 Subject: [PATCH] Add better support for note/warning types and update docs appopriately --- core/dronecore.h | 8 ++--- generate_markdown_from_doxygen_xml.py | 48 +++++++++++---------------- plugins/action/action.h | 2 +- plugins/action/action_result.h | 2 +- 4 files changed, 26 insertions(+), 34 deletions(-) diff --git a/core/dronecore.h b/core/dronecore.h index 03468eea82..b86eeb9b44 100644 --- a/core/dronecore.h +++ b/core/dronecore.h @@ -54,7 +54,7 @@ class DroneCore * Default URL : udp://:14540. * - Default Bind host IP is localhost(127.0.0.1) * - * Warning: serial connections are not supported on Windows (they are supported on Linux and macOS). + * @warning Serial connections are not supported on Windows (they are supported on Linux and macOS). * * @param connection_url connection URL string. * @return The result of adding the connection. @@ -83,7 +83,7 @@ class DroneCore * @brief Adds a serial connection with a specific port (COM or UART dev node) and baudrate as specified. * * - * Warning: this method is not supported on Windows (it is supported on Linux and macOS). + * @warning This method is not supported on Windows (it is supported on Linux and macOS). * * @param dev_path COM or UART dev node name/path (defaults to "/dev/ttyS0"). * @param baudrate Baudrate of the serial port (defaults to 57600). @@ -160,7 +160,7 @@ class DroneCore * If systems have been discovered before this callback is registered, they will be notified * at the time this callback is registered. * - * **Note** Only one callback can be registered at a time. If this function is called several + * @note Only one callback can be registered at a time. If this function is called several * times, previous callbacks will be overwritten. * * @param callback Callback to register. @@ -174,7 +174,7 @@ class DroneCore * This sets a callback that will be notified if no heartbeat of the system has been received * in 3 seconds. * - * **Note** Only one callback can be registered at a time. If this function is called several + * @note Only one callback can be registered at a time. If this function is called several * times, previous callbacks will be overwritten. * * @param callback Callback to register. diff --git a/generate_markdown_from_doxygen_xml.py b/generate_markdown_from_doxygen_xml.py index 99c548dac6..1012d7a2a5 100755 --- a/generate_markdown_from_doxygen_xml.py +++ b/generate_markdown_from_doxygen_xml.py @@ -96,9 +96,9 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False): if child.attrib['kind']=='return': pass # simplesect contains return info for function. We parse it specifically in other code so here we make sure it this tag doesn't get processed. elif child.attrib['kind']=='see': - pass #Prevent further handling of "see" children. - elif child.attrib['kind']=='note': - pass #Prevent further handling of "note" children. + pass #Prevent further handling of "see" children. + elif child.attrib['kind']=='warning' or child.attrib['kind']=='note' or child.attrib['kind']=='since' or child.attrib['kind']=='attention' or child.attrib['kind']=='remark': #Pass 'note' types to specific handling + child_text += markdown_any_tag(child,html=html,para=para) #.strip() //Handle warnings individually else: #Just in case there is a different type of simplesect, this tells us we need to think about it. print('Unhanded kind in simplesect tag in markdown_any_tag:kind: %s' % child.attrib['kind']) @@ -158,7 +158,7 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False): tag_text=lead_text+child_text+tail_text elif aTag.tag=='itemizedlist': if html: - tag_text='\n'+tail_text + tag_text='\n'+tail_text else: tag_text='\n'+lead_text+child_text+tail_text+'\n' #single level implementation. elif aTag.tag=='listitem': @@ -200,39 +200,31 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False): tag_text=lead_text+tail_text #note, child text included in the URL text above. There won't be any though. #print('tag_text: %s' % tag_text) - elif aTag.tag=='detaileddescription': - #Strip out note tags from detailed description (so it can be agreggated under Notes section) - note_tags=aTag.findall(".//simplesect[@kind='note']") - note_text='' - if note_tags: - for item in note_tags: - note_text+='\n%s' % markdown_any_tag(item).strip() - - note_text='\n\n**Notes:**\n\n%s\n\n' % note_text - #print('debug:tag:note_text: %s' % note_text) - - #Strip out seealso tags from detailed description (so it can be agreggated under Seealso section) - """ - seealso_tags=aTag.findall(".//simplesect[@kind='see']") - seealso_text='' - if seealso_tags: - for item in seealso_tags: - seealso_text+='\n- %s' % markdown_any_tag(item).strip() - - seealso_text='\n\n**See Also:**%s\n\n' % seealso_text - #print('debug:tag:seealso_text: %s' % seealso_text) - """ - tag_text=lead_text+child_text+note_text+tail_text + elif aTag.tag=='detaileddescription': + tag_text=lead_text+child_text+tail_text elif aTag.tag=='simplesect': - if aTag.attrib['kind']=='note' or aTag.attrib['kind']=='see' or aTag.attrib['kind']=='return': + if aTag.attrib['kind']=='see' or aTag.attrib['kind']=='return': #Handle @note (note) and @sa (see) tags. # Note we should ONLY see this via the detaileddescription handling # Because children that are simplesect are not parsed. tag_text=lead_text+child_text+tail_text + #Convert "note" types + if aTag.attrib['kind']=='warning' or aTag.attrib['kind']=='note' or aTag.attrib['kind']=='attention': + #print('Debug: kind %s' % aTag.attrib['kind']) + noteTypeText=aTag.attrib['kind'].capitalize() + if para: + if html: + tag_text='

'+lead_text+''+noteTypeText+': '+child_text+'

'+tail_text + else: # ONLY THIS PATH TESTED (others should not occur, but leaving in as standard. + tag_text='\n\n> **'+noteTypeText+'** '+lead_text.strip()+child_text.strip()+'\n\n'+tail_text.strip() + else: #para disabled, render without them. + tag_text='\n\n> **'+noteTypeText+'** '+ lead_text.strip()+child_text.strip()+tail_text.strip() + + elif aTag.tag=='verbatim': tag_text='\n\n'+lead_text+child_text+'\n\n'+tail_text diff --git a/plugins/action/action.h b/plugins/action/action.h index b269d4a6d7..a858abd476 100644 --- a/plugins/action/action.h +++ b/plugins/action/action.h @@ -47,7 +47,7 @@ class Action : public PluginBase /** * @brief Send command to *arm* the drone (synchronous). * - * **Note** Arming a drone normally causes motors to spin at idle. + * @note Arming a drone normally causes motors to spin at idle. * Before arming take all safety precautions and stand clear of the drone! * * @return ActionResult of request. diff --git a/plugins/action/action_result.h b/plugins/action/action_result.h index bd97ece301..6f40c5ceb6 100644 --- a/plugins/action/action_result.h +++ b/plugins/action/action_result.h @@ -8,7 +8,7 @@ namespace dronecore { /** * @brief Possible results returned for commanded actions. * - * **Note**: DroneCore does not throw exceptions. Instead a result of this type will be + * @note DroneCore does not throw exceptions. Instead a result of this type will be * returned when you execute actions. */ enum class ActionResult {