<div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><div>Hi!<br><br>I do see the value of having a consistent format across all clang project's documentation. But a more important aspect is to have better visibility.<br></div>Right now we have analyzer related documentation:<br></div>* In docs/analyzer folder<br></div><div>* At the analyzer's homepage<br>* lib/StaticAnalyzer/README.txt<br></div><div>* The checker in 24 hour talk<br></div><div>* We have <a href="https://github.com/haoNoQ/clang-analyzer-guide">https://github.com/haoNoQ/clang-analyzer-guide</a><br><br></div><div>Having one updated place as a single source of truth would be a great QoL improvement which could make it easier to get started with the analyzer.<br></div><div>I think the lack of such place is one of the biggest obstacles for newcomers.<br><br></div><div>Having a more consistent style of documentation with clang tidy for the individual checkers is also a plus from the user's point of view.<br></div><div>The current per checker documentation at the analyzer's homepage is often lacking. They are great for getting an idea what a check is about but they do not cover all of the detected cases, do not cover configuration options and do not give the user any advice how to actually solve the problems and what is the best way to suppress potential false positives.<br><br></div><div>BTW, are there any users who rely on the analyzer distribution on the analyzer's homepage rather than the analyzer within a clang distribution? If we do not support that separate distribution I would rather remove it from the analyzer's homepage regardless of the decision of moving the site to the common format.<br></div><div><br></div><div>Regards,<br></div><div>Gabor<br></div><div dir="ltr"><div><div> <br></div></div></div></div></div></div><br><div class="gmail_quote"><div dir="ltr">On Tue, 13 Nov 2018 at 16:50, Dániel Krupp via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org">cfe-dev@lists.llvm.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div lang="EN-US" link="#0563C1" vlink="#954F72">
<div class="m_7987779587301843633WordSection1">
<p class="MsoNormal">Dear Analyzer Community,<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">Most standard Clang tools (ThreadSanitizer, MemorySanitizer, DataFlowSanitizer etc.)<br>
have documentation delivered with Clang and build using Sphinx tool at <a href="https://clang.llvm.org/docs/" target="_blank"><span style="color:#136cb2">https://clang.llvm.org/docs/</span></a>.<br>
I thought it would be great to have the ClangSA docs there too in sphinx markup.<u></u><u></u></span></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white;font-variant-ligatures:normal;font-variant-caps:normal;text-decoration-style:initial;text-decoration-color:initial;word-spacing:0px">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">I created a patch
<a href="https://reviews.llvm.org/D54429" target="_blank">https://reviews.llvm.org/D54429</a> where analyzer's documentation main page and the checker sub-pages are<br>
transformed into Sphinx RST.<u></u><u></u></span></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">This is how it looks like now:<u></u><u></u></span></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black"><a href="http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html" target="_blank"><span style="color:#136cb2">http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html</span></a><u></u><u></u></span></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white;font-variant-ligatures:normal;font-variant-caps:normal;text-decoration-style:initial;text-decoration-color:initial;word-spacing:0px">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">Advantages:<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:22.5pt;line-height:20.4pt;background:white">
<u></u><span style="font-size:10.0pt;font-family:Symbol;color:black"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">The documentation is easier to be maintained in Sphinx markup compared to raw HTML<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:22.5pt;line-height:20.4pt;background:white">
<u></u><span style="font-size:10.0pt;font-family:Symbol;color:black"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">The documentation is easier found in the standard clang doc tree<u></u><u></u></span></p>
<p class="MsoNormal" style="margin-left:22.5pt;line-height:20.4pt;background:white">
<u></u><span style="font-size:10.0pt;font-family:Symbol;color:black"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">The generated documentation looks nicer ;)<u></u><u></u></span></p>
<p class="MsoNormal"><br>
What was also missing (for many users) is the documentation of the checkers. Similar to the one-pagers what we have for clang-tidy:
<a href="http://clang.llvm.org/extra/clang-tidy/checks/list.html" target="_blank">http://clang.llvm.org/extra/clang-tidy/checks/list.html</a><br>
<br>
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">So a similar listing page is created:
<a href="http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html" target="_blank">http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html</a><br>
With a specific one-pager example: <a href="http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html" target="_blank">
<span style="color:#136cb2">http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html</span></a></span><u></u><u></u></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black"><br>
In practice the pages can be migrated one by one (after sanitizing them) and at end a redirection can be set up at
<a href="https://clang-analyzer.llvm.org/" target="_blank">https://clang-analyzer.llvm.org/</a></span><span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif">.<span style="color:black"><u></u><u></u></span></span></p>
<p style="margin-right:0in;margin-bottom:9.0pt;margin-left:0in;background:white">
<span style="font-size:10.0pt;font-family:"Segoe UI",sans-serif;color:black">I wonder what you guys think about this approach?<br>
</span><br>
Thanks,<br>
Daniel<u></u><u></u></p>
</div>
</div>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@lists.llvm.org" target="_blank">cfe-dev@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev</a><br>
</blockquote></div>