[cfe-dev] GSoD: analyzer checker docs?

[Kristóf Umann via cfe-dev]

Yup, consider me convinced.

On Sat, 20 Apr 2019 at 04:45, Artem Dergachev <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> 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> 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.
>>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20190420/e69254a7/attachment.html>