Merge pull request #544 from denniszollo/settings_doc_clarity

Settings doc clarity (WIP)

Makefile

@@ -52,7 +52,7 @@ help:
 	@echo "  test      to run all tests"
 	@echo
 
-all: deps-generator c python javascript java haskell docs
+all: deps-generator c python javascript java docs haskell
 docs: verify-prereq-docs deps-generator pdf html
 
 c:          deps-c          gen-c          test-c

c/include/libsbp/settings.h

@@ -17,13 +17,32 @@
 
 /** \defgroup settings Settings
  *
- *  * Messages for reading and writing the device's device settings.
+ *  * 
+ * Messages for reading, writing, and discovering device settings. Settings
+ * with a "string" field have multiple values in this field delimited with a
+ * null character (the c style null terminator).  For instance, when querying
+ * the 'firmware_version' setting in the 'system_info' section, the following
+ * array of characters needs to be sent for the string field in
+ * MSG_SETTINGS_READ: "system_info\0firmware_version\0", where the delimiting 
+ * null characters are specified with the escape sequence '\0' and all
+ * quotation marks should be omitted. 
  * 
- * Note that some of these messages share the same message type ID for both the
- * host request and the device response. See the accompanying document for
- * descriptions of settings configurations and examples:
  * 
- * https://github.com/swift-nav/piksi\_firmware/blob/master/docs/settings.pdf
+ * In the message descriptions below, the generic strings SECTION_SETTING and
+ * SETTING are used to refer to the two strings that comprise the identifier
+ * of an individual setting.In firmware_version example above, SECTION_SETTING
+ * is the 'system_info', and the SETTING portion is 'firmware_version'. 
+ * 
+ * See the "Software Settings Manual" on support.swiftnav.com for detailed
+ * documentation about all settings and sections available for each Swift
+ * firmware version. Settings manuals are available for each firmware version
+ * at the following link: https://support.swiftnav.com/customer/en/portal/articles/2628580-piksi-multi-specifications#settings.
+ * The latest settings document is also available at the following link: 
+ * http://swiftnav.com/latest/piksi-multi-settings .
+ * See lastly https://github.com/swift-nav/piksi_tools/blob/master/piksi_tools/settings.py , 
+ * the open source python command line utility for reading, writing, and
+ * saving settings in the piksi_tools repository on github as a helpful
+ * reference and example.
  * \{ */
 
 #ifndef LIBSBP_SETTINGS_MESSAGES_H
@@ -42,14 +61,18 @@
 
 /** Write device configuration settings (host => device)
  *
-* The setting message writes the device configuration.
+ * The setting message writes the device configuration for a particular
+ * setting via A NULL-terminated and NULL-delimited string with contents
+ * "SECTION_SETTING\0SETTING\0VALUE\0" where the '\0' escape sequence denotes 
+ * the NULL character and where quotation marks are omitted. A device will
+ * only process to this message when it is received from sender ID 0x42.
+ * An example string that could be sent to a device is
+ * "solution\0soln_freq\010\0".
  */
 #define SBP_MSG_SETTINGS_WRITE              0x00A0
 typedef struct __attribute__((packed)) {
-  char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING, VALUE]. A device will only
-process to this message when it is received from sender ID
-0x42.
+  char setting[0]; /**< A NULL-terminated and NULL-delimited string with contents
+"SECTION_SETTING\0SETTING\0VALUE\0"
  */
 } msg_settings_write_t;
 
@@ -58,49 +81,64 @@ process to this message when it is received from sender ID
  *
  * Return the status of a write request with the new value of the
  * setting.  If the requested value is rejected, the current value
- * will be returned.
+ * will be returned. The string field is a NULL-terminated and NULL-delimited
+ * string with contents "SECTION_SETTING\0SETTING\0VALUE\0" where the '\0'
+ * escape sequence denotes the NULL character and where quotation marks
+ * are omitted. An example string that could be sent from device is
+ * "solution\0soln_freq\010\0".
  */
 #define SBP_MSG_SETTINGS_WRITE_RESP         0x00AF
 typedef struct __attribute__((packed)) {
   u8 status;     /**< Write status */
   char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING, VALUE].
+"SECTION_SETTING\0SETTING\0VALUE\0" 
  */
 } msg_settings_write_resp_t;
 
 
 /** Read device configuration settings (host => device)
  *
-* The setting message reads the device configuration.
+ * The setting message that reads the device configuration. The string
+ * field is a NULL-terminated and NULL-delimited string with contents
+ * "SECTION_SETTING\0SETTING\0" where the '\0' escape sequence denotes the
+ * NULL character and where quotation marks are omitted. An example
+ * string that could be sent to a device is "solution\0soln_freq\0". A
+ * device will only respond to this message when it is received from
+ * sender ID 0x42. A device should respond with a MSG_SETTINGS_READ_RESP
+ * message (msg_id 0x00A5).
  */
 #define SBP_MSG_SETTINGS_READ_REQ           0x00A4
 typedef struct __attribute__((packed)) {
-  char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING]. A device will only respond to
-this message when it is received from sender ID 0x42.
+  char setting[0]; /**< A NULL-terminated and NULL-delimited string with contents
+"SECTION_SETTING\0SETTING\0"
  */
 } msg_settings_read_req_t;
 
 
 /** Read device configuration settings (host <= device)
  *
-* The setting message reads the device configuration.
+ * The setting message wich which the device responds after a
+ * MSG_SETTING_READ_REQ is sent to device. The string field is a
+ * NULL-terminated and NULL-delimited string with contents
+ * "SECTION_SETTING\0SETTING\0VALUE\0" where the '\0' escape sequence
+ * denotes the NULL character and where quotation marks are omitted. An
+ * example string that could be sent from device is
+ * "solution\0soln_freq\010\0".
  */
 #define SBP_MSG_SETTINGS_READ_RESP          0x00A5
 typedef struct __attribute__((packed)) {
-  char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING, VALUE].
+  char setting[0]; /**< A NULL-terminated and NULL-delimited string with contents
+"SECTION_SETTING\0SETTING\0VALUE\0"
+ 
  */
 } msg_settings_read_resp_t;
 
 
 /** Read setting by direct index (host => device)
  *
  * The settings message for iterating through the settings
- * values. It will read the setting at an index, returning a
- * NULL-terminated and delimited string with contents
- * [SECTION_SETTING, SETTING, VALUE]. A device will only respond to
- * this message when it is received from sender ID 0x42.
+ * values. A device will respond to this message with a 
+ * "MSG_SETTINGS_READ_BY_INDEX_RESP".
  */
 #define SBP_MSG_SETTINGS_READ_BY_INDEX_REQ  0x00A2
 typedef struct __attribute__((packed)) {
@@ -112,18 +150,24 @@ typedef struct __attribute__((packed)) {
 
 /** Read setting by direct index (host <= device)
  *
- * The settings message for iterating through the settings
- * values. It will read the setting at an index, returning a
- * NULL-terminated and delimited string with contents
- * [SECTION_SETTING, SETTING, VALUE].
+ * The settings message that reports the value of a setting at an index.
+ * 
+ * In the string field, it reports NULL-terminated and delimited string
+ * with contents "SECTION_SETTING\0SETTING\0VALUE\0FORMAT_TYPE\0". where
+ * the '\0' escape sequence denotes the NULL character and where quotation
+ * marks are omitted. The FORMAT_TYPE field is optional and denotes
+ * possible string values of the setting as a hint to the user. If
+ * included, the format type portion of the string has the format
+ * "enum:value1,value2,value3". An example string that could be sent from
+ * the device is "simulator\0enabled\0True\0enum:True,False\0"
  */
 #define SBP_MSG_SETTINGS_READ_BY_INDEX_RESP 0x00A7
 typedef struct __attribute__((packed)) {
   u16 index;      /**< An index into the device settings, with values ranging from
 0 to length(settings)
  */
   char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING, VALUE].
+"SECTION_SETTING\0SETTING\0VALUE\0FORMAT_TYPE\0"
  */
 } msg_settings_read_by_index_resp_t;
 
@@ -144,7 +188,7 @@ typedef struct __attribute__((packed)) {
 #define SBP_MSG_SETTINGS_REGISTER           0x00AE
 typedef struct __attribute__((packed)) {
   char setting[0]; /**< A NULL-terminated and delimited string with contents
-[SECTION_SETTING, SETTING, VALUE].
+"SECTION_SETTING\0SETTING\0VALUE".
  */
 } msg_settings_register_t;
 

generator/sbpg/targets/c.py

@@ -14,6 +14,7 @@
 """
 
 from sbpg.targets.templating import *
+from sbpg.utils import markdown_links
 
 MESSAGES_TEMPLATE_NAME = "sbp_messages_template.h"
 VERSION_TEMPLATE_NAME = "sbp_version_template.h"
@@ -22,6 +23,7 @@ def commentify(value):
   """
   Builds a comment.
   """
+  value = markdown_links(value)
   if value is None:
     return
   if len(value.split('\n')) == 1:

generator/sbpg/targets/haskell.py

@@ -16,6 +16,7 @@
 import string
 import copy
 from sbpg.targets.templating import *
+from sbpg.utils import comment_links
 
 MESSAGES_TEMPLATE_NAME = "SbpMessagesTemplate.hs"
 CABAL_TEMPLATE_NAME = "sbp-template.cabal"
@@ -143,6 +144,9 @@ def to_put(f, type_map=PUT_CONSTRUCT_CODE):
     return "mapM_ %s" % to_put(f_, type_map)
   return type_map.get(name, "put")
 
+def comment_links_hsk(s):
+  return '\<' + comment_links(s) + '\>'
+
 def max_fid_len(m):
   """
   Max field id length.
@@ -156,6 +160,7 @@ def max_fid_len(m):
 JENV.filters['to_put'] = to_put
 JENV.filters['max_fid_len'] = max_fid_len
 JENV.filters['camel_case'] = camel_case
+JENV.filters['comment_links'] = comment_links_hsk
 
 def render_source(output_dir, package_spec):
   """

generator/sbpg/targets/java.py

@@ -20,7 +20,7 @@
 import os
 import os.path
 from sbpg.targets.templating import JENV, ACRONYMS
-
+from sbpg.utils import comment_links
 
 TEMPLATE_NAME = "sbp_java.java.j2"
 TEMPLATE_TABLE_NAME = "MessageTable.java.j2"
@@ -61,6 +61,7 @@ def commentify(value):
   """
   Builds a comment.
   """
+  value = comment_links(value)
   if value is None:
     return
   if len(value.split('\n')) == 1:

generator/sbpg/targets/javascript.py

@@ -17,6 +17,7 @@
 """
 
 from sbpg.targets.templating import JENV
+from sbpg.utils import comment_links
 import copy
 import textwrap
 
@@ -176,6 +177,7 @@ def islist(x):
 JENV.filters['arrayLength'] = array_length
 JENV.filters['construct_js'] = construct_format
 JENV.filters['jsdoc'] = jsdoc_format
+JENV.filters['comment_links'] = comment_links
 JENV.filters['starWordWrap'] = star_wordwrap
 JENV.filters['starWordWrapIndent'] = star_wordwrap_indent
 

generator/sbpg/targets/latex.py

@@ -45,9 +45,9 @@ def no_us(value):
 LATEX_SUBS = (
     (re.compile(r'\\'), r'\\textbackslash'),
     (re.compile(r'([{}_#%&$])'), r'\\\1'),
+    (re.compile(r'@@(\S+)\[(.+)\]'), r'\href{\1}{\2}'),
     (re.compile(r'~'), r'\~{}'),
     (re.compile(r'\^'), r'\^{}'),
-    (re.compile(r'_'), r'_'),
     (re.compile(r'"'), r"''"),
     (re.compile(r'\.\.\.+'), r'\\ldots'),
 )

generator/sbpg/targets/python.py

@@ -17,6 +17,7 @@
 """
 
 from sbpg.targets.templating import JENV, ACRONYMS
+from sbpg.utils import comment_links
 import copy
 
 TEMPLATE_NAME = "sbp_construct_template.py.j2"
@@ -97,6 +98,7 @@ def classnameify(s):
 JENV.filters['construct_py'] = construct_format
 JENV.filters['classnameify'] = classnameify
 JENV.filters['pydoc'] = pydoc_format
+JENV.filters['comment_links'] = comment_links
 
 
 def render_source(output_dir, package_spec, jenv=JENV):

generator/sbpg/targets/resources/SbpMessagesTemplate.hs

@@ -11,7 +11,7 @@
 -- Stability:   experimental
 -- Portability: portable
 --
--- (((description | replace("\n", " ") | wordwrap(width=76, wrapstring="\n-- "))))
+-- (((description | comment_links | replace("\n", " ") | wordwrap(width=76, wrapstring="\n-- " ))))
 
 module (((module_name)))
   ( module (((module_name)))

generator/sbpg/targets/resources/sbp_construct_template.py.j2

@@ -11,7 +11,7 @@
 
 
 """
-(((description)))
+(((description|comment_links)))
 """
 
 import json

generator/sbpg/targets/resources/sbp_js.js.j2

@@ -15,7 +15,7 @@
  **********************
  * Package description:
  *
- * (((description | starWordWrap)))
+ * (((description | comment_links | starWordWrap)))
 ***********************/
 
 var SBP = require('./sbp');

generator/sbpg/targets/resources/sbp_messages_desc.tex

@@ -4,9 +4,9 @@
 \section{Stable Message Definitions}
 ((*- for m in msgs *))
 ((*- if m.pkg *))
-\subsection{(((m.pkg|packagenameify|header_write)))}
+\subsection{(((m.pkg|packagenameify|header_write|no_us)))}
 \begin{large}
-(((m.pkg_desc | escape_tex | no_us)))
+(((m.pkg_desc | escape_tex )))
 \end{large}
 ((* endif *))
 \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id)))) --- (((m.sbp_id)))}
@@ -94,7 +94,7 @@ \subsection{(((m.pkg|packagenameify|no_us|header_write)))}
 (((m.pkg_desc)))
 \end{large}
 ((* endif *))
-\subsubsection*{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id)))) --- (((m.sbp_id)))}
+\subsubsection*{(((m.name|escape_tex|no_us))) --- ((('0x%04X'|format(m.sbp_id)))) --- (((m.sbp_id)))}
 \label{sec:(((m.name)))}
 \begin{minipage}{\textwidth}
 \begin{large}

generator/sbpg/utils.py

@@ -10,7 +10,7 @@
 # WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 
 import pprint
-
+import re
 def fmt_repr(obj):
   """
   Return pretty printed string representation of an object.
@@ -52,3 +52,11 @@ def rejig_bitfields(bfs):
             'len': bf_len,
         }))
     return new_bfs, n_with_values
+
+def comment_links(input_string):
+   pattern = re.compile(r'@@(\S+)\[(.+)\]')
+   return pattern.sub( r'\1', input_string) 
+
+def markdown_links(input_string):
+   pattern = re.compile(r'@@(\S+)\[(.+)\]')
+   return pattern.sub( r'[\2](\1)', input_string)