<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
Mm, writing actual in-depth analyzer doc for developers in GSoD
would be pretty hard unless we pick, say, Kristóf as our technical
writer. Even throughout GSoC, where studends who spend 3 months
working on the analyzer in practice, by the end of the summer they
often don't gather enough understanding to start writing this sort
of docs. We can't expect an outside technical writer (who's not
necessarily that much of a programmer) to dive into this so quickly.<br>
<br>
I also feel that we don't need someone else's help with our
documentation for developers: we're writing good documentation
ourselves, we just need to put it together somehow. It is the skill
of writing documentation for regular users that, i think, we all are
missing.<br>
<br>
<br>
<div class="moz-cite-prefix">On 4/19/19 6:58 PM, Devin Coughlin
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:1C7BD16C-FA50-4F2F-BB0F-0344FB6B4171@apple.com">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
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!
<div class=""><br class="">
</div>
<div class="">One area that would be great to improve on is
describing for our important checkers:</div>
<div class="">* What bugs does the checker find?</div>
<div class="">* Why are the bugs important?</div>
<div class="">* How should the bugs be fixed?</div>
<div class="">* How should false positives be suppressed?</div>
<div class=""><br class="">
</div>
<div class="">The GSoD project is an amazing resource — we should
take advantage of it to improve our users’ experience of the
analyzer.</div>
<div class=""><br class="">
</div>
<div class="">Devin</div>
<div class="">
<div><br class="">
<blockquote type="cite" class="">
<div class="">On Apr 19, 2019, at 4:37 PM, Kristóf Umann
<<a href="mailto:dkszelethus@gmail.com" class=""
moz-do-not-send="true">dkszelethus@gmail.com</a>>
wrote:</div>
<br class="Apple-interchange-newline">
<div class="">
<div dir="ltr" class="">
<div dir="ltr" class="">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 <a
href="https://clang-analyzer.llvm.org/" class=""
moz-do-not-send="true">https://clang-analyzer.llvm.org/</a>,
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.</div>
<div dir="ltr" class=""><br class="">
</div>
<div class="">Couple thoughts of mine, I haven't read
through the entire GSoD procedure thought.</div>
</div>
<br class="">
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Sat, 20 Apr 2019 at
03:12, Artem Dergachev <<a
href="mailto:noqnoqneo@gmail.com" class=""
moz-do-not-send="true">noqnoqneo@gmail.com</a>>
wrote:<br class="">
</div>
<blockquote class="gmail_quote" style="margin:0px 0px
0px 0.8ex;border-left:1px solid
rgb(204,204,204);padding-left:1ex">Tanya made this
call for Google thing of Docs, which is like summer of
<br class="">
code just for docs <br class="">
(<a
href="http://lists.llvm.org/pipermail/cfe-dev/2019-April/062121.html"
rel="noreferrer" target="_blank" class=""
moz-do-not-send="true">http://lists.llvm.org/pipermail/cfe-dev/2019-April/062121.html</a>).
<br class="">
There's been a lot of work on checker docs in the
Analyzer recently. Do <br class="">
we want to take this opportunity?<br class="">
<br class="">
Like, if it gives us a nice, stylish,
easy-to-understand, on-point <br class="">
description of what the checker thinks the user's code
is doing and how <br class="">
bad does it think it is, it might be pretty neat.<br
class="">
</blockquote>
</div>
</div>
</blockquote>
</div>
<br class="">
</div>
</blockquote>
<br>
</body>
</html>