Patchwork [i-g-t,1/2] lib: avoid < in gtkdoc comments

login
register
mail settings
Submitter Daniel Vetter
Date Nov. 29, 2017, 11:17 a.m.
Message ID <20171129111755.25825-1-daniel.vetter@ffwll.ch>
Download mbox | patch
Permalink /patch/10081917/
State New
Headers show

Comments

Daniel Vetter - Nov. 29, 2017, 11:17 a.m.
For reasons entirely not clear to me meson gtkdoc runs in strict
xml parsing mode, whereas automake gtkdoc doesn't. And gtkdoc itself
is tooooooooo dense to correctly escape this stuff.

Paper around this.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 lib/igt_aux.c     | 4 ++--
 lib/igt_core.c    | 4 ++--
 lib/igt_debugfs.c | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)
Joonas Lahtinen - Dec. 4, 2017, 1:53 p.m.
On Wed, 2017-11-29 at 12:17 +0100, Daniel Vetter wrote:
> For reasons entirely not clear to me meson gtkdoc runs in strict
> xml parsing mode, whereas automake gtkdoc doesn't. And gtkdoc itself
> is tooooooooo dense to correctly escape this stuff.
> 
> Paper around this.
> 
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

&lt;foo> looks trippy.

As we're not trying to document HTML stuff, maybe simly <foo> ->
${foo}. I'm pretty sure everyone will be comfortable with that
notation.

Regards, Joonas

Patch

diff --git a/lib/igt_aux.c b/lib/igt_aux.c
index 0bcf792c64e9..62b30ce0e01b 100644
--- a/lib/igt_aux.c
+++ b/lib/igt_aux.c
@@ -1000,7 +1000,7 @@  void igt_drop_root(void)
  * @var: var lookup to to enable this wait
  *
  * Waits for a key press when run interactively and when the corresponding debug
- * var is set in the --interactive-debug=<var> variable. Multiple keys
+ * var is set in the --interactive-debug=$var variable. Multiple keys
  * can be specified as a comma-separated list or alternatively "all" if a wait
  * should happen for all cases.
  *
@@ -1041,7 +1041,7 @@  void igt_debug_wait_for_keypress(const char *var)
  * @expected: message to be printed as expected behaviour before wait for keys Y/n
  *
  * Waits for a key press when run interactively and when the corresponding debug
- * var is set in the --interactive-debug=<var> variable. Multiple vars
+ * var is set in the --interactive-debug=$var variable. Multiple vars
  * can be specified as a comma-separated list or alternatively "all" if a wait
  * should happen for all cases.
  *
diff --git a/lib/igt_core.c b/lib/igt_core.c
index 6ce83becd18b..5f1d1d34dbc6 100644
--- a/lib/igt_core.c
+++ b/lib/igt_core.c
@@ -164,10 +164,10 @@ 
  *   test logic.
  *
  * - When adding a new feature test function which uses igt_skip() internally,
- *   use the <prefix>_require_<feature_name> naming scheme. When you
+ *   use the &lt;prefix>_require_&lt;feature_name> naming scheme. When you
  *   instead add a feature test function which returns a boolean, because your
  *   main test logic must take different actions depending upon the feature's
- *   availability, then instead use the <prefix>_has_<feature_name>.
+ *   availability, then instead use the &lt;prefix>_has_&lt;feature_name>.
  *
  * - As already mentioned eschew explicit error handling logic as much as
  *   possible. If your test absolutely has to handle the error of some function
diff --git a/lib/igt_debugfs.c b/lib/igt_debugfs.c
index 5670099f1480..156c1d45ef58 100644
--- a/lib/igt_debugfs.c
+++ b/lib/igt_debugfs.c
@@ -231,7 +231,7 @@  int igt_debugfs_dir(int device)
  * @mode: mode bits as used by open()
  *
  * This opens a debugfs file as a Unix file descriptor. The filename should be
- * relative to the drm device's root, i.e. without "drm/<minor>".
+ * relative to the drm device's root, i.e. without "drm/$minor".
  *
  * Returns:
  * The Unix file descriptor for the debugfs file or -1 if that didn't work out.