[clang] [NFC][analyzer] Rewrite comment header of MallocChecker (PR #165443)

[Donát Nagy via cfe-commits]

NagyDonat wrote:

> To me the most interesting point it this comment of the PR summary:
> 
> > I see that this block is a bit verbose (especially compared to the analogous comments in other checkers), but as this is one of the most complex checker families, I think it's useful to give this overview at the beginning of the source file.
> 
> I'm all for comments like this. This is the right place to document the design and the overall architecture. Potentially also including some ascii-art if applicable. You probably know that IMO a comment inline in code should be brief, preferably a single line or two, and under very exceptional cases more.

@steakhal Thanks for clarifying this! I included that reasoning in the PR summary because after our last discussion about long comments (which were in the middle of the code and turned out to be mostly unnecessary – I was able to shorten them) I felt that you would perhaps oppose this other long comment as well.

> The comment there would take up precious lines and make you scroll through. In contrast to this a comment at the top of the file has plenty of space, and a newcomer could (and should) opt in reading these.

It seems that I have unusually high natural tolerance for comment blocks that take up lines and break the flow of the code, but I'll pay attention to this issue when I write comments. (To me, even a very large comment block is much less issue than a layer of indirection where I need to "Jump to definition" to see what happens behind that ambiguous function name.)

https://github.com/llvm/llvm-project/pull/165443