jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

style: add a section on examples 

addressing:
* anchoring
* content of example

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
This commit is contained in:
Vincent Batts 2016-03-17 02:31:09 +00:00
parent 547e00b42e
commit 7dbab778ed
1 changed files with 65 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
style.md
View File

@ -21,6 +21,70 @@ The redundancy reduction from removing the namespacing prefix is not useful enou
So we have a consistent way to identify unset values ([source][optional-pointer]).
The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).
## Examples
### Anchoring
For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
The level of header should be such that it is a subheader of the header it is an example of.
#### Example
```markdown
## Some Topic
### Some Subheader
#### Further Subheader
##### Example
To use Further Subheader, ...
### Example
To use Some Topic, ...
```
### Content
Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.
Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned.
Most commonly onlookers will intend to copy-and-paste a "working example".
If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such.
```markdown
### Example
```
```json
{
"foo": null,
"bar": ""
}
```
**vs.**
```markdown
### Example
Following is a fully populated example (not necessarily for copy/paste use)
```
```json
{
"foo": [
1,
2,
3
],
"bar": "waffles",
"bif": {
"baz": "potatoes"
}
}
```
[capabilities]: config-linux.md#capabilities
[class-id]: config-linux.md#network
@ -30,3 +94,4 @@ The exceptions are entries where the Go default for the type is a no-op in the s
[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
[optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706
[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings