doc/lint/chap5

   1 .NH 1
   2 How to make lint shut up
   3 .PP
   4 It can be very annoying having
   5 .I lint
   6 warn about questionable constructs of which the programmer already is
   7 aware.
   8 There should be a mechanism to give
   9 .I lint
  10 some extra information in the source code.
  11 This could be done by introducing some special keywords, which
  12 would have a special meaning to
  13 .I lint.
  14 This is a bad solution, because these keywords would cause existing
  15 C compilers not to work on these programs.
  16 A neater solution is to invent some comments having a special
  17 meaning to
  18 .I lint.
  19 We call these comments
  20 .I pseudocomments.
  21 The pseudocomments have no meaning to existing C compilers, so
  22 compilers will not have to be rewritten for C programs containing
  23 the previously proposed special keywords.
  24 The following pseudocomments are recognized by
  25 .I lint.
  26 .LP
  27 \f(CW/* VARARGS\fIn\fP */\fR
  28 .br
  29 .in 5
  30 The next function can be called with a variable number of arguments.
  31 Only check the first \fIn\fP arguments.
  32 The \fIn\fP must follow the word \f(CWVARARGS\fP immediately.
  33 This pseudocomment is useful for functions like e.g. printf.
  34 (The definition of the function printf should be preceded by
  35 \f(CW/*\ VARARGS1\ */\fP.)
  36 .in
  37 .LP
  38 \f(CW/* VARARGS */\fP
  39 .br
  40 .in 5
  41 Means the same as \f(CW/* VARARGS0 */\fP.
  42 .in
  43 .LP
  44 \f(CW/* ARGSUSED */\fP
  45 .br
  46 .in 5
  47 Don't complain about unused arguments in the next function.
  48 When we are developing a program we sometimes write functions of
  49 which we do not yet use the arguments.
  50 Because we do want to use
  51 .I lint
  52 on these programs, it is nice to have this pseudocomment.
  53 .in
  54 .LP
  55 \f(CW/* NOTREACHED */\fP
  56 .br
  57 .in 5
  58 .I Lint
  59 makes no attempt to discover functions which never return,
  60 although it \fIis\fP possible to find functions that don't return.
  61 This would require a transitive closure with respect to the already
  62 known \fInot-returning\fP functions; an inacceptable time consuming
  63 process.
  64 To make
  65 .I lint
  66 aware of a function that doesn't return, a call of this function
  67 should be followed by the pseudocomment \f(CW/*\ NOTREACHED\ */\fP.
  68 This pseudocomment can also be used to indicate that some case part
  69 inside a switch (especially a default part) can't be reached.
  70 The above mentioned cases of use of this pseudocomment are
  71 examples.
  72 The comment can be used just to indicate that some part of the
  73 program can't be reached.
  74 It sometimes is necessary to introduce an extra compound statement
  75 to get the right effect.
  76 See figure 9.
  77 .KF
  78 .DS B
  79 .ft CW
  80         if (cond)
  81                 /* if part */ ;
  82         else {
  83                 error();  /* doesn't return */
  84                 /* NOTREACHED */
  85         }
  86 /* Without  the compound  else  part, lint  would  assume
  87  * the statement after the if statement to be NOTREACHED,
  88  * instead of the end of the else part.
  89  */
  90 .I
  91 .DE
  92 .ce
  93 figure\ 9.
  94 .R
  95 .KE
  96 .in
  97 .LP
  98 \f(CW/* LINTLIBRARY */\fP
  99 .br
 100 .in 5
 101 All definitions following this comment are assumed to be library
 102 definitions.
 103 It shuts off complaints about unused functions and variables.
 104 See also section 4.2.7 for how to use this comment for generating
 105 lint libraries.
 106 .in
 107 .bp