You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/qldoc-style-guide.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ Valid QL comments are known as QLDoc. This document describes the recommended st
12
12
1. Use `/** ... */` for documentation, even for single line comments.
13
13
- For single-line documentation, the `/**` and `*/` are written on the same line as the comment.
14
14
- For multi-line documentation, the `/**` and `*/` are written on separate lines. There is a `*` preceding each comment line, aligned on the first `*`.
15
-
1. Use code formatting (`backticks`) within comments for code from the source language, and also for QL code (for example, names of classes, predicates, and variables).
15
+
1. Use code formatting (backticks) within comments for code from the source language, and also for QL code (for example, names of classes, predicates, and variables).
16
16
1. Give explanatory examples of code in the target language, enclosed in ```` ``` ```` or `` ` ``.
17
17
18
18
@@ -43,7 +43,7 @@ Valid QL comments are known as QLDoc. This document describes the recommended st
43
43
44
44
### Predicates without result
45
45
46
-
1. Use a third-person verb phrase of the form ``Holds if `arg` has <property>.``.
46
+
1. Use a third-person verb phrase of the form ``Holds if `arg` has <property>.``
47
47
1. Avoid:
48
48
-`/** Whether ... */`
49
49
-`/**" Relates ... */`
@@ -65,9 +65,9 @@ Valid QL comments are known as QLDoc. This document describes the recommended st
65
65
66
66
1. Use a third-person verb phrase of the form `Gets (a|the) <thing>`.
67
67
1. Use "if any" if the item is usually unique but might be missing. For example
68
-
`Gets the body of this method, if any.`.
68
+
`Gets the body of this method, if any.`
69
69
1. If the predicate has more complex behaviour, for example multiple arguments are conceptually "outputs", it can be described like a predicate without a result. For example
70
-
``Holds if `result` is a child of this expression.``.
70
+
``Holds if `result` is a child of this expression.``
Some predicates are internal-only declarations that cannot be made private. The documentation for internal predicates should begin with `INTERNAL: Do not use.`.
99
+
Some predicates are internal-only declarations that cannot be made private. The documentation for internal predicates should begin with `INTERNAL: Do not use.`
100
100
101
101
#### Example
102
102
@@ -170,8 +170,8 @@ Modules should be documented using a third-person verb phrase of the form `Provi
170
170
/** Provides logic for determining constant expressions. */
171
171
```
172
172
```ql
173
-
/** Provides classes representing the control flow graph within functions. */
174
-
```
173
+
/** Provides classes representing the control flow graph within functions. */
0 commit comments