The original homepage of CSA has been out-of-date for a long time. And some recent papers even consider we are dropped out and out-of-support (see the link below). What should we do about this situation? At least, something needs to be done for the URL (clang-analyzer.llvm.org).
I think I would object. It’s certainly true, the it doesn’t move quickly. We should be more transparent, e.g. we should at least have release notes for each release.
However, I’m not exactly paid for doing anything like that, which is bad. I imagine, the same applies to the rest of the folks here. And given that we aren’t many, it’s hard to find contributors consolidating this situation.
I would say, you are one of the rare.
Personally, I’d prefer dropping that page and favor https://clang.llvm.org/docs/ClangStaticAnalyzer.html instead.
However, given that that page refers to the other as “official tool page”, I’m not too sure.
Anyway, either that or the other surely needs some cleanup and finally consolidate all the links to a single one.
Yes, the website is broken because SSI directives suddenly stopped working, so there’s no menu navigation anymore, and I never got around to fix it If we find a way to fix it, or just inline them, it’ll be in a much better shape. Given that I haven’t had a chance to do that recently, I’m probably in no position to object against this proposal ^.^
I was hesitant to inline them because that’s insane code duplication, but it’s not like we’re working on that code anyway, so maybe this is fine. This could be a stop-gap solution while we carry over useful stuff to RST.
There’s some valuable material on the website that we probably don’t want to lose:
- the FAQ is quite useful (at least some of it), FAQ and How to Deal with Common False Positives
- the attributes page also probably needs to stay, Source Annotations
- the checker dev manual definitely needs to be carried over, Checker Developer Manual
Most importantly though, the front page needs to have a picture. We need to set the expectation that we display arrows and bubbles all over your code when we deliver a single warning, so that users didn’t ever miss that part.
I always wondered if we could also have some “live” examples by linking to some full compiler explorer snippets. But I’m not sure as we don’t recommend using CSA directly, but rather via some wrapper like scan-build or CodeChecker and maybe even via clang-tidy. Actually, that might be quite useful to draw attention.
I think godbolt examples could be great for some of the more technical pages, like the checker dev manual. Maybe they’re also good for regular pages as long as we include a screenshot every time we use it (and then a tiny (try it live on godbolt!) link next to it).
They’re somewhat hard to maintain though; if we change something in the static analyzer and the warning is no longer emitted, the godbolt page will never tell us that. What we probably want to do is, make a LIT test for every godbolt invocation we add (in addition to the exact test case, it needs to have a flag to freeze the target architecture to whatever godbolt is using), and then every time these tests intentionally break, it should be really obvious that godbolt links in documentation need to be updated accordingly.