Skip to content
Permalink
Browse files
[FLINK-20900][docs] Added guidelines for documenting commands.
  • Loading branch information
XComp authored and rmetzger committed Jan 12, 2021
1 parent 7e801f8 commit 6a9a6a96c0c481c35c0b762ec3b299672f5bacde
Showing 1 changed file with 26 additions and 0 deletions.
@@ -463,6 +463,32 @@ Or using plain HTML:
might not be obvious from reading it. Use comments to clarify
implementation details and to describe the expected output.

* **Commands in code blocks.** Commands can be documented using `bash` syntax
highlighted code blocks. The following items should be considered when adding
commands to the docummentation:
* **Use long parameter names.** Long parameter names help the reader to
understand the purpose of the command. They should be preferred over their
short counterparts.
* **One parameter per line.** Using long parameter names makes the command
possibly harder to read. Putting one parameter per line improves the
readability. You need to add a backslash `\` escaping the newline at
the end of each intermediate line to support copy&paste.
* **Indentation**. Each new parameter line should be indented by 6 spaces.
* **Use `$` prefix to indicate command start**. The readability of the code
block might worsen having multiple commands in place. Putting a dollar sign
`$` in front of each new commands helps identifying the start of a
command.

A properly formatted command would look like this:

```bash
$ ./bin/flink run-application \
--target kubernetes-application \
-Dkubernetes.cluster-id=my-first-application-cluster \
-Dkubernetes.container.image=custom-image-name \
local:///opt/flink/usrlib/my-flink-job.jar
```

[Back to top](#top)

## General Guiding Principles

0 comments on commit 6a9a6a9

Please sign in to comment.