瀏覽代碼

README-documentation-rules.md: Mention not listing types in param/returns docs.

Ryan C. Gordon 8 月之前
父節點
當前提交
a0591ec4a3
共有 1 個文件被更改,包括 9 次插入0 次删除
  1. 9 0
      docs/README-documentation-rules.md

+ 9 - 0
docs/README-documentation-rules.md

@@ -242,6 +242,15 @@ wikiheaders will complain loudly if you don't do this, and exit with an
 error message.
 error message.
 
 
 
 
+## Don't repeat type names in `\param` and `\returns` sections.
+
+Wikiheaders will explicitly mention the datatype for each parameter and the
+return value, linking to the datatype's wikipage. Users reading the headers
+can see the types in the function signature right below the documentation
+comment. So don't mention the type a second time in the documentation if
+possible. It looks cluttered and repetitive to do so.
+
+
 ## Code examples go in the wiki.
 ## Code examples go in the wiki.
 
 
 We don't want the headers cluttered up with code examples. These live on the
 We don't want the headers cluttered up with code examples. These live on the