[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)

[Balázs Kéri via cfe-commits]

https://github.com/balazske updated https://github.com/llvm/llvm-project/pull/83858

>From bb81a944b78315471df8866bf21b317e8c50166c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20K=C3=A9ri?= <balazs.keri at ericsson.com>
Date: Mon, 4 Mar 2024 09:48:41 +0100
Subject: [PATCH 1/2] [clang][analyzer] Improve documentation of StreamChecker
 (NFC).

---
 clang/docs/analyzer/checkers.rst | 66 +++++++++++++++++++++++++-------
 1 file changed, 52 insertions(+), 14 deletions(-)

diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index fe211514914272..aa79792c64dc54 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl
 
 alpha.unix.Stream (C)
 """""""""""""""""""""
-Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,``
-``fsetpos, clearerr, feof, ferror, fileno``.
+Check C stream handling functions:
+``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``.
+
+The checker maintains information about the C stream objects (``FILE *``) and
+can detect error conditions related to use of streams. The following conditions
+are detected:
+
+* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
+  NULL is allowed.)
+* Use of stream after close.
+* Opened stream is not closed.
+* Read from a stream after end-of-file. (This is not a fatal error but reported
+  by the checker. Stream remains in EOF state and the read operation fails.)
+* Use of stream when the file position is indeterminate after a previous failed
+  operation. Some functions are allowed in this state.
+* Invalid 3rd ("``whence``") argument to ``fseek``.
+
+The checker is not capable of maintaining a relation between integer file
+descriptors and ``FILE *`` pointers. Operations on standard streams like
+``stdin`` are not treated specially and are therefore often not recognized
+(because these streams are usually not opened explicitly by the program, and
+are global variables).
 
 .. code-block:: c
 
- void test() {
+ void test1() {
    FILE *p = fopen("foo", "r");
  } // warn: opened file is never closed
 
- void test() {
+ void test2() {
    FILE *p = fopen("foo", "r");
    fseek(p, 1, SEEK_SET); // warn: stream pointer might be NULL
    fclose(p);
  }
 
- void test() {
+ void test3() {
    FILE *p = fopen("foo", "r");
+   if (p) {
+     fseek(p, 1, 3); // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+     fclose(p);
+   }
+ }
 
-   if (p)
-     fseek(p, 1, 3);
-      // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+ void test4() {
+   FILE *p = fopen("foo", "r");
+   if (!p)
+     return;
 
    fclose(p);
+   fclose(p); // warn: stream already closed
  }
 
- void test() {
+ void test5() {
    FILE *p = fopen("foo", "r");
+   if (!p)
+     return;
+
+   fgetc(p);
+   if (!ferror(p))
+     fgetc(p); // warn: possible read after end-of-file
+
    fclose(p);
-   fclose(p); // warn: already closed
  }
 
- void test() {
-   FILE *p = tmpfile();
-   ftell(p); // warn: stream pointer might be NULL
+ void test6() {
+   FILE *p = fopen("foo", "r");
+   if (!p)
+     return;
+
+   fgetc(p);
+   if (!feof(p))
+     fgetc(p); // warn: file position may be indeterminate after I/O error
+
    fclose(p);
  }
 
-
 .. _alpha-unix-cstring-BufferOverlap:
 
 alpha.unix.cstring.BufferOverlap (C)

>From 5d723d165331b9a3e38a2ea1c9ff83b70745b6e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20K=C3=A9ri?= <balazs.keri at ericsson.com>
Date: Tue, 5 Mar 2024 10:25:46 +0100
Subject: [PATCH 2/2] maked documentation more exact

---
 clang/docs/analyzer/checkers.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index aa79792c64dc54..e6eb7c2ced620c 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3027,21 +3027,21 @@ The checker maintains information about the C stream objects (``FILE *``) and
 can detect error conditions related to use of streams. The following conditions
 are detected:
 
-* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
-  NULL is allowed.)
+* The ``FILE *`` pointer passed to the function is NULL (the single exception is
+  ``fflush`` where NULL is allowed).
 * Use of stream after close.
 * Opened stream is not closed.
 * Read from a stream after end-of-file. (This is not a fatal error but reported
   by the checker. Stream remains in EOF state and the read operation fails.)
 * Use of stream when the file position is indeterminate after a previous failed
-  operation. Some functions are allowed in this state.
+  operation. Some functions (like ``ferror``, ``clearerr``, ``fseek``) are
+  allowed in this state.
 * Invalid 3rd ("``whence``") argument to ``fseek``.
 
-The checker is not capable of maintaining a relation between integer file
-descriptors and ``FILE *`` pointers. Operations on standard streams like
-``stdin`` are not treated specially and are therefore often not recognized
-(because these streams are usually not opened explicitly by the program, and
-are global variables).
+The checker does not track the correspondence between integer file descriptors
+and ``FILE *`` pointers. Operations on standard streams like ``stdin`` are not
+treated specially and are therefore often not recognized (because these streams
+are usually not opened explicitly by the program, and are global variables).
 
 .. code-block:: c