Re: [PATCH/wwwdocs] add uses of @code to coding conventions

[Jeff Law]

On 12/13/18 4:34 PM, Martin Sebor wrote:
> Attached is the update I propose to add to the Spelling,
> terminology and markup section of the Coding conventions, to
> give guidance for when to use the @code{} Texinfo command.
>  I believe this reflects existing (if somewhat inconsistent)
> practice.  It's not intended to add a new requirement.
> 
OK.  And yes, it's just documenting what's supposed to be standard
practice rather than adding new requirements.


Jeff

[PATCH/wwwdocs] add uses of @code to coding conventions

[Martin Sebor]

Attached is the update I propose to add to the Spelling,
terminology and markup section of the Coding conventions, to
give guidance for when to use the @code{} Texinfo command.
 I believe this reflects existing (if somewhat inconsistent)
practice.  It's not intended to add a new requirement.

Martin
Index: htdocs/codingconventions.html
===
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.90
diff -u -r1.90 codingconventions.html
--- htdocs/codingconventions.html	1 Dec 2018 17:19:36 -	1.90
+++ htdocs/codingconventions.html	13 Dec 2018 23:34:00 -
@@ -569,6 +569,17 @@
   required if the capital letter is within @code or
   @samp.)
 
+  Use @code for an expression in a program, for the name
+  of a variable or function used in a program, or for a keyword in
+  a programming language.  However, avoid @code in uses
+  of language keywords as adjectives.  For example, appropriate uses
+  of @code are in phrases such as
+  "@code{const}-qualified type", or
+  "@code{asm} statement", or
+  "function returns @code{true}".
+  Examples where @code should be avoided are phrases such as
+  "const variable", "volatile access", or
+  "condition is false."