[cfe-dev] GSoD: analyzer checker docs?

[Artem Dergachev via cfe-dev]

All right, i missed the deadline because i didn't keep track of it in my 
head. I still think it was a good idea to try, i guess let's try next 
year in a less hasty manner.

On 4/19/19 8:12 PM, Kristóf Umann wrote:
> Yup, consider me convinced.
>
> On Sat, 20 Apr 2019 at 04:45, Artem Dergachev <noqnoqneo at gmail.com 
> <mailto:noqnoqneo at gmail.com>> wrote:
>
>     I don't fully understand this either, but it's pretty hard to
>     imagine that somebody from outside would be able to quickly
>     understand how Static Analyzer works and uses this understanding
>     solely for describing how it works. Even a GSoC student doesn't
>     necessarily gather enough understanding throughout a summer of
>     practical work on the analyzer to write such docs. On the other
>     hand, about the docs that are scattered around - it's bad that
>     they're scattered around, but they themselves aren't that bad
>     (well, at least, i arrogantly believe they aren't that bad), just
>     hard to find. I mean, they don't look like something that somebody
>     should write for us; we'll probably do a better job writing
>     in-depth docs because we're writing it for ourselves and we know
>     what we need.
>
>     On 4/19/19 6:58 PM, Devin Coughlin wrote:
>>     I think we should try to focus the Google Summer of Documentation
>>     project on documenting aspects of the analyzer that would benefit
>>     our users. There are a lot more of them than there are of us
>>     analyzer developers!
>>
>>     One area that would be great to improve on is describing for our
>>     important checkers:
>>     * What bugs does the checker find?
>>     * Why are the bugs important?
>>     * How should the bugs be fixed?
>>     * How should false positives be suppressed?
>>
>>     The GSoD project is an amazing resource — we should take
>>     advantage of it to improve our users’ experience of the analyzer.
>>
>>     Devin
>>
>>>     On Apr 19, 2019, at 4:37 PM, Kristóf Umann
>>>     <dkszelethus at gmail.com <mailto:dkszelethus at gmail.com>> wrote:
>>>
>>>     Sounds like the thing we always needed in my opinion! The
>>>     analyzer could really use some better docs in certain areas --
>>>     speaking from personal experience, I always thought that I just
>>>     need more time to learning about the codebase before being able
>>>     to understand patches related to, for example, liveness
>>>     analysis. It wasn't until I attended Gábor Horváth's advanced
>>>     compilers lectures at my university, when I understood that that
>>>     is in fact something that exists in the literature, and the
>>>     thing that we have in the analyzer is "merely" an implementation
>>>     of it. I really liked what he said during the Birds of a Feather
>>>     meeting on EuroLLVM, is that we do have many things documented,
>>>     but it's scattered all over the place in youtube videos, cfe-dev
>>>     mails, patch review discussions, bugzilla reports (especially
>>>     before 2012) and the like. If under GSoD we could get this
>>>     sorted out, get rid of most of HTML files we have on
>>>     https://clang-analyzer.llvm.org/, and have an easy-to-navigate,
>>>     easy-to-extend documentation for the long term, it would be far
>>>     more inviting for newcomers as well. I might be biased, but the
>>>     Clang Static Analyzer is very cool project, and I think if we
>>>     made the transition from writing your first checker to making
>>>     changes in the actual infrastructure a little easier, we would
>>>     have a a lot easier time building a community around it.
>>>
>>>     Couple thoughts of mine, I haven't read through the entire GSoD
>>>     procedure thought.
>>>
>>>     On Sat, 20 Apr 2019 at 03:12, Artem Dergachev
>>>     <noqnoqneo at gmail.com <mailto:noqnoqneo at gmail.com>> wrote:
>>>
>>>         Tanya made this call for Google thing of Docs, which is like
>>>         summer of
>>>         code just for docs
>>>         (http://lists.llvm.org/pipermail/cfe-dev/2019-April/062121.html).
>>>
>>>         There's been a lot of work on checker docs in the Analyzer
>>>         recently. Do
>>>         we want to take this opportunity?
>>>
>>>         Like, if it gives us a nice, stylish, easy-to-understand,
>>>         on-point
>>>         description of what the checker thinks the user's code is
>>>         doing and how
>>>         bad does it think it is, it might be pretty neat.
>>>
>>
>