un-nest curl

curl-8.15.0/docs/internals/CHECKSRC.md

@@ -0,0 +1,190 @@
+<!--
+Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+
+SPDX-License-Identifier: curl
+-->
+
+# checksrc
+
+This is the tool we use within the curl project to scan C source code and
+check that it adheres to our [Source Code Style guide](CODE_STYLE.md).
+
+## Usage
+
+    checksrc.pl [options] [file1] [file2] ...
+
+## Command line options
+
+`-W[file]` skip that file and exclude it from being checked. Helpful
+when, for example, one of the files is generated.
+
+`-D[dir]` directory name to prepend to filenames when accessing them.
+
+`-h` shows the help output, that also lists all recognized warnings
+
+## What does `checksrc` warn for?
+
+`checksrc` does not check and verify the code against the entire style guide.
+The script is an effort to detect the most common mistakes and syntax mistakes
+that contributors make before they get accustomed to our code style. Heck,
+many of us regulars do the mistakes too and this script helps us keep the code
+in shape.
+
+    checksrc.pl -h
+
+Lists how to use the script and it lists all existing warnings it has and
+problems it detects. At the time of this writing, the existing `checksrc`
+warnings are:
+
+- `ASSIGNWITHINCONDITION`: Assignment within a conditional expression. The
+  code style mandates the assignment to be done outside of it.
+
+- `ASTERISKNOSPACE`: A pointer was declared like `char* name` instead of the
+   more appropriate `char *name` style. The asterisk should sit next to the
+   name.
+
+- `ASTERISKSPACE`: A pointer was declared like `char * name` instead of the
+   more appropriate `char *name` style. The asterisk should sit right next to
+   the name without a space in between.
+
+- `BADCOMMAND`: There is a bad `checksrc` instruction in the code. See the
+   **Ignore certain warnings** section below for details.
+
+- `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf,
+   strcat, strncat, gets are **never** allowed in curl source code.
+
+- `BRACEELSE`: '} else' on the same line. The else is supposed to be on the
+   following line.
+
+- `BRACEPOS`: wrong position for an open brace (`{`).
+
+- `BRACEWHILE`: more than once space between end brace and while keyword
+
+- `COMMANOSPACE`: a comma without following space
+
+- `COPYRIGHT`: the file is missing a copyright statement
+
+- `CPPCOMMENTS`: `//` comment detected, that is not C89 compliant
+
+- `DOBRACE`: only use one space after do before open brace
+
+- `EMPTYLINEBRACE`: found empty line before open brace
+
+- `EQUALSNOSPACE`: no space after `=` sign
+
+- `EQUALSNULL`: comparison with `== NULL` used in if/while. We use `!var`.
+
+- `EXCLAMATIONSPACE`: space found after exclamations mark
+
+- `FOPENMODE`: `fopen()` needs a macro for the mode string, use it
+
+- `INDENTATION`: detected a wrong start column for code. Note that this
+   warning only checks some specific places and can certainly miss many bad
+   indentations.
+
+- `LONGLINE`: A line is longer than 79 columns.
+
+- `MULTISPACE`: Multiple spaces were found where only one should be used.
+
+- `NOSPACEEQUALS`: An equals sign was found without preceding space. We prefer
+  `a = 2` and *not* `a=2`.
+
+- `NOTEQUALSZERO`: check found using `!= 0`. We use plain `if(var)`.
+
+- `ONELINECONDITION`: do not put the conditional block on the same line as `if()`
+
+- `OPENCOMMENT`: File ended with a comment (`/*`) still "open".
+
+- `PARENBRACE`: `){` was used without sufficient space in between.
+
+- `RETURNNOSPACE`: `return` was used without space between the keyword and the
+   following value.
+
+- `SEMINOSPACE`: There was no space (or newline) following a semicolon.
+
+- `SIZEOFNOPAREN`: Found use of sizeof without parentheses. We prefer
+  `sizeof(int)` style.
+
+- `SNPRINTF` - Found use of `snprintf()`. Since we use an internal replacement
+   with a different return code etc, we prefer `msnprintf()`.
+
+- `SPACEAFTERPAREN`: there was a space after open parenthesis, `( text`.
+
+- `SPACEBEFORECLOSE`: there was a space before a close parenthesis, `text )`.
+
+- `SPACEBEFORECOMMA`: there was a space before a comma, `one , two`.
+
+- `SPACEBEFOREPAREN`: there was a space before an open parenthesis, `if (`,
+   where one was not expected
+
+- `SPACESEMICOLON`: there was a space before semicolon, ` ;`.
+
+- `TABS`: TAB characters are not allowed
+
+- `TRAILINGSPACE`: Trailing whitespace on the line
+
+- `TYPEDEFSTRUCT`: we frown upon (most) typedefed structs
+
+- `UNUSEDIGNORE`: a `checksrc` inlined warning ignore was asked for but not
+   used, that is an ignore that should be removed or changed to get used.
+
+### Extended warnings
+
+Some warnings are quite computationally expensive to perform, so they are
+turned off by default. To enable these warnings, place a `.checksrc` file in
+the directory where they should be activated with commands to enable the
+warnings you are interested in. The format of the file is to enable one
+warning per line like so: `enable <EXTENDEDWARNING>`
+
+Currently these are the extended warnings which can be enabled:
+
+- `COPYRIGHTYEAR`: the current changeset has not updated the copyright year in
+   the source file
+
+- `STRERROR`: use of banned function strerror()
+
+- `STDERR`: use of banned variable `stderr`
+
+## Ignore certain warnings
+
+Due to the nature of the source code and the flaws of the `checksrc` tool,
+there is sometimes a need to ignore specific warnings. `checksrc` allows a few
+different ways to do this.
+
+### Inline ignore
+
+You can control what to ignore within a specific source file by providing
+instructions to `checksrc` in the source code itself. See examples below. The
+instruction can ask to ignore a specific warning a specific number of times or
+you ignore all of them until you mark the end of the ignored section.
+
+Inline ignores are only done for that single specific source code file.
+
+Example
+
+    /* !checksrc! disable LONGLINE all */
+
+This ignores the warning for overly long lines until it is re-enabled with:
+
+    /* !checksrc! enable LONGLINE */
+
+If the enabling is not performed before the end of the file, it is enabled
+again automatically for the next file.
+
+You can also opt to ignore just N violations so that if you have a single long
+line you just cannot shorten and is agreed to be fine anyway:
+
+    /* !checksrc! disable LONGLINE 1 */
+
+... and the warning for long lines is enabled again automatically after it has
+ignored that single warning. The number `1` can of course be changed to any
+other integer number. It can be used to make sure only the exact intended
+instances are ignored and nothing extra.
+
+### Directory wide ignore patterns
+
+This is a method we have transitioned away from. Use inline ignores as far as
+possible.
+
+Make a `checksrc.skip` file in the directory of the source code with the
+false positive, and include the full offending line into this file.