Skip to contentSkip to conversation

ucm: docs: typeset lists of identifiers explicitly

PATCH Superseded Antonio Ospite 1 participant 2 messages Sep 21, 2016

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 ucm: docs: typeset lists of identifiers explicitly

Doxygen doesn't preserve formatting that relies only on indentation, typeset lists of identifiers explicitly.

This makes the HTML docs a lot more readable.

This change comes along the lines of commit 72aa0f8332fb ("ucm: reformat snd_use_case_get() doc").

Some TABs has been added too in order to preserve the aligned look when reading the source code.

---
 include/use-case.h | 57 +++++++++++++++++++++++++++---------------------------
 1 file changed, 29 insertions(+), 28 deletions(-)
include/use-case.h +29 -28
index 9aac6e2..1ebd945 100644
@@ -192,20 +192,21 @@ int snd_use_case_free_list(const char *list[], int items);
  * \return Number of list entries if success, otherwise a negative error code
  *
  * Defined identifiers:
- *   NULL 		- get card list
- *			  (in pair cardname+comment)
- *   _verbs		- get verb list
- *			  (in pair verb+comment)
- *   _devices[/{verb}]	- get list of supported devices
- *			  (in pair device+comment)
- *   _modifiers[/{verb}]- get list of supported modifiers
- *			  (in pair modifier+comment)
- *   TQ[/{verb}]	- get list of TQ identifiers
- *   _enadevs		- get list of enabled devices
- *   _enamods		- get list of enabled modifiers
+ *   - NULL			- get card list
+ *				 (in pair cardname+comment)
+ *   - _verbs			- get verb list
+ *				  (in pair verb+comment)
+ *   - _devices[/{verb}]	- get list of supported devices
+ *				  (in pair device+comment)
+ *   - _modifiers[/{verb}]	- get list of supported modifiers
+ *				  (in pair modifier+comment)
+ *   - TQ[/{verb}]		- get list of TQ identifiers
+ *   - _enadevs			- get list of enabled devices
+ *   - _enamods			- get list of enabled modifiers
+ *
+ *   - _supporteddevs/{modifier}|{device}[/{verb}]   - list of supported devices
+ *   - _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
  *
- *   _supporteddevs/{modifier}|{device}[/{verb}]   - list of supported devices
- *   _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
  *   Note that at most one of the supported/conflicting devs lists has
  *   any entries, and when neither is present, all devices are supported.
  *
@@ -331,8 +332,8 @@ int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
  * \return Zero if success, otherwise a negative error code
  *
  * Known identifiers:
- *   _devstatus/{device}	- return status for given device
- *   _modstatus/{modifier}	- return status for given modifier
+ *   - _devstatus/{device}	- return status for given device
+ *   - _modstatus/{modifier}	- return status for given modifier
  */
 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
 		      const char *identifier,
@@ -346,19 +347,19 @@ int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
  * \return Zero if success, otherwise a negative error code
  *
  * Known identifiers:
- *   _verb 		- set current verb = value
- *   _enadev		- enable given device = value
- *   _disdev		- disable given device = value
- *   _swdev/{old_device} - new_device = value
- *			- disable old_device and then enable new_device
- *			- if old_device is not enabled just return
- *			- check transmit sequence firstly
- *   _enamod		- enable given modifier = value
- *   _dismod		- disable given modifier = value
- *   _swmod/{old_modifier} - new_modifier = value
- *			- disable old_modifier and then enable new_modifier
- *			- if old_modifier is not enabled just return
- *			- check transmit sequence firstly
+ *   - _verb			- set current verb = value
+ *   - _enadev			- enable given device = value
+ *   - _disdev			- disable given device = value
+ *   - _swdev/{old_device}	- new_device = value
+ *				  - disable old_device and then enable new_device
+ *				  - if old_device is not enabled just return
+ *				  - check transmit sequence firstly
+ *   - _enamod			- enable given modifier = value
+ *   = _dismod			- disable given modifier = value
+ *   - _swmod/{old_modifier}	- new_modifier = value
+ *				  - disable old_modifier and then enable new_modifier
+ *				  - if old_modifier is not enabled just return
+ *				  - check transmit sequence firstly
  */
 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
                      const char *identifier,
Signature · 1 line
2.9.3
#1 lore raw
Quoted 3 lines · On Wed, 21 Sep 2016 15:52:45 +0200 Antonio Ospite <[email protected]> wrote:

Doxygen doesn't preserve formatting that relies only on indentation, typeset lists of identifiers explicitly.

[...]

Quoted 8 lines
---
 include/use-case.h | 57 +++++++++++++++++++++++++++---------------------------
 1 file changed, 29 insertions(+), 28 deletions(-)
include/use-case.h +0 -0
index 9aac6e2..1ebd945 100644

[...]

Quoted 1 line
include/use-case.h +0 -0
@@ -346,19 +347,19 @@ int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,

[...]

Quoted 1 line

+ * = _dismod - disable given modifier = value

Here there should be a '-' in place of the first '=', I only noticed after sending.

I'll wait some days before sending a v2, or feel free to amend the patch locally if that's not too much burden.

Thanks,
Antonio

Signature · 7 lines
Antonio Ospite
https://ao2.it
https://twitter.com/ao2it

A: Because it messes up the order in which people normally read text.
   See http://en.wikipedia.org/wiki/Posting_style
Q: Why is top-posting such a bad thing?