From 0c72c9d2f1853624e49058507a2c33dfcf3f2dec Mon Sep 17 00:00:00 2001 From: Larpon Date: Mon, 30 Nov 2020 18:49:57 +0100 Subject: [PATCH] doc: mention present tense convention, explain long comments (#7036) --- doc/docs.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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`.