[analyzer] Add docs for cplusplus.InnerPointer

[Szelethus]

Summary

Tried to pick two interesting examples from the tests.
This check has no options.

[Szelethus]

Woohoo!

docs/analyzer/checkers.rst

225–226 ↗

(On Diff #193762)

Hmm. While this page is a documentation, I would still expect regular users to browse through it -- are we sure that we want to add future plans for a non-alpha checker? I'm not against it, just a question.

[dkrupp]

docs/analyzer/checkers.rst

225–226 ↗

(On Diff #193762)

I think it is a good idea. A non-alpha checker can also be further developed, by anyone else. It is good that we don't forget about further features. This note also highlights the limitations of the checker.

[Szelethus]

docs/analyzer/checkers.rst

225–226 ↗

(On Diff #193762)

How about this: "Future plans include to add support for blahblah". The current statement should rather be a TODO in the code.

[NoQ]

docs/analyzer/checkers.rst

225–226 ↗

(On Diff #193762)

I suggest presenting it as "The checker is currently limited to std::strings and doesn't recognize some of the more sophisticated approaches to passing unowned pointers around, such as std::string_views". It sounds a bit more negative than it deserves to sound, but that's the most documentation-like text i managed to come up with so far >.< Maybe put it under a "Known Limitations:" marker and/or expand the main part of the documentation in order to keep the reader's impression balanced, eg. "Many container methods in the C++ standard library are known to invalidate "references" (including actual references, iterators and raw pointers) to elements of the container. Using such references after they are invalidated causes undefined behavior, which is a common source of memory errors in C++ that this checker is capable of finding."

While this page is a documentation, I would still expect regular users to browse through it

I'd love our users to browse it! Maybe we should consider adding a documentation link to our HTML report headers as the documentation gets good enough.

232 ↗

(On Diff #193762)

The test_ part doesn't add much here, maybe drop it?

[Szelethus]

I'll gladly add the finishing touches :)

[rnkovacs]

In D60281#1630337, @Szelethus wrote:

I'll gladly add the finishing touches :)

So sorry for leaving this hanging!
Thanks Husi, you da best :)

[Szelethus]

Revised the documentation according to @NoQ's comments. By literally copy pasting it. Like any good programmer should do :^)

[NoQ]

clang/docs/analyzer/checkers.rst

263

I suggest deref_after_assignment.

271

Let's turn this into a parameter so that to avoid an uninitialized use (and generally be more realistic).

[Szelethus]

Fixed!

[NoQ]

Thanks!

One more quick question: Who is Husi???

clang/docs/analyzer/checkers.rst

261

This declaration doesn't add much to the documentation, feel free to remove it :)

[Szelethus]

In D60281#1630646, @NoQ wrote:

Thanks!

One more quick question: Who is Husi???

Well thats me. Long story short, the reason why my name is Szelethus is that my first ever character to hit max level in World of Warcraft was called Szelethús. It literally means "slice of meat" in Hungarian. When I got to university, we were instructed to pick a nickname at the beginning of the freshman camp, where the shorthand version "Husi" ("meat", pronounced along the lines of "hushie") was born, and stuck on me ever since. So aside from my parents, I'm universally called that, even in the office.

[NoQ]

Cute!!

clang/docs/analyzer/checkers.rst

 
 cplusplus
 ^^^^^^^^^
 
 C++ Checkers.
 
 .. _cplusplus-InnerPointer:
 
-cplusplus.InnerPointer
-""""""""""""""""""""""
+cplusplus.InnerPointer (C++)
+""""""""""""""""""""""""""""
 Check for inner pointers of C++ containers used after re/deallocation.
 
+Many container methods in the C++ standard library are known to invalidate
+"references" (including actual references, iterators and raw pointers) to
+elements of the container. Using such references after they are invalidated
+causes undefined behavior, which is a common source of memory errors in C++ that
+this checker is capable of finding.
+
+The checker is currently limited to ``std::string`` objects and doesn't
+recognize some of the more sophisticated approaches to passing unowned pointers
+around, such as ``std::string_view``.
+
+.. code-block:: cpp
+
+ void consume(const char *);
+
+ void deref_after_assignment() {
+   std::string s = "llvm";
+   const char *c = s.data(); // note: pointer to inner buffer of 'std::string' obtained here
+   s = "clang"; // note: inner buffer of 'std::string' reallocated by call to 'operator='
+   consume(c); // warn: inner pointer of container used after re/deallocation
+ }
+
+ const char *return_temp(int x) {
+   return std::to_string(x).c_str(); // warn: inner pointer of container used after re/deallocation
+   // note: pointer to inner buffer of 'std::string' obtained here
+   // note: inner buffer of 'std::string' deallocated by call to destructor
+ }
+
 .. _cplusplus-NewDelete:
 
 cplusplus.NewDelete (C++)
 """""""""""""""""""""""""
 Check for double-free and use-after-free problems. Traces memory managed by new/delete.
 
 .. literalinclude:: checkers/newdelete_example.cpp
     :language: cpp