[doc] Switch from pipes to backticks in comments
The aim of this switch is to ensure we can render monospaced text (and
other markdown) in C and C++ api comments. Doxygen will render markdown
in code comments, but doesn't understand pipe characters.
Signed-off-by: Sam Elliott <selliott@lowrisc.org>
diff --git a/doc/rm/c_cpp_coding_style.md b/doc/rm/c_cpp_coding_style.md
index 0fb84c3..48e68cf 100644
--- a/doc/rm/c_cpp_coding_style.md
+++ b/doc/rm/c_cpp_coding_style.md
@@ -60,14 +60,18 @@
***Comments should be `// C99-style` for consistency with C++.***
-***Variables mentioned in comments should be delimited with pipe (`|`) characters.***
+<!-- To render a backtick in inline code in markdown, you need to double the surrounding backticks.
+https://daringfireball.net/projects/markdown/syntax#code -->
+***Variables mentioned in comments should be delimited with backtick (`` ` ``) characters.***
Example:
```c
-// |ptr| can never be NULL for reasons.
+// `ptr` can never be NULL for reasons.
```
+Note also [Public function (API) documentation](#public-function-api-documentation) below.
+
### TODO Comments
***TODO comments should be in the format `TODO: message`.***
@@ -114,6 +118,9 @@
The first line of the comment is the summary, followed by a new line, and an optional longer description.
Input arguments and return arguments can be documented with `@param` and `@return` if they are not self-explanatory from the name.
+The `@p` modifier can be used to format the following word as monospaced text in the final output.
+The documentation tool will also render markdown within descriptions.
+
Example:
```c
