diff --git a/doc/docs.md b/doc/docs.md
index 2af503fde2..21c1f6e3d5 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -2496,6 +2496,19 @@ fn clearall() {
 
 The comment must start with the name of the definition.
 
+Sometimes one line isn't enough to explain what a function does, in that case comments should
+span to the documented function using single line comments:
+
+```v
+// copy_all recursively copies all elements of the array by their value,
+// if `dupes` is false all duplicate values are eliminated in the process.
+fn copy_all(dupes bool) {
+	// ...
+}
+```
+
+By convention it is preferred that comments are written in *present tense*.
+
 An overview of the module must be placed in the first comment right after the module's name.
 
 To generate documentation use vdoc, for example `v doc net.http`.