Browse Source

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

Ryan C. Gordon 9 tháng trước cách đây
mục cha
commit
a0591ec4a3

+ 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