<html><head><meta http-equiv="Content-Type" content="text/html charset=iso-8859-1"><meta http-equiv="Content-Type" content="text/html charset=iso-8859-1"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Sam, thank you so much for working on this!</div><div><br></div><div>Here are some comments. However, this generally looks good.</div><div><br></div><div>Anna.</div><div><br></div><div>---- Custom Program states</div><div>+<p></div><div>+Checkers often need to extend the program state information to include their own</div><div>+custom information. The preferred way to do so is to use one of several macros</div><div>+designed for this purpose. They are:</div><div>+</div><div><br></div><div>Mention that checkers are stateless and the callbacks are not guaranteed to occur in a predetermined order, so checkers have to update the ProgramState to store their own state.</div><div><br></div><div><div>+<p>These macros will cover a majority of use cases; however, they still have a</div><div>+few limitations. They cannot be used inside namespaces (since they expand to</div><div>+contain top-level namespace references), and the data types that they define</div><div>+cannot be referenced from more than one file.</div></div><div><br></div><div>I would just say "Note that the macros cannot be used inside namespaces (since they expand to contain top-level namespace references)." The macros can be referred to from multiple files if they are defined in a header that is included from all of them. It's just that each checker is usually contained in a single file.</div><div><br></div><div>How about restructuring the section a bit to group the intro/explanation of each macro and their getters and setters together?</div><div><br></div><div>---- Checker Registration</div><div>We should refer to SimpleStreamChecker here. We should probably remove the checker class from the code since it will be described next in the Checker Skeleton section.</div><div><br></div><div>---- Checker Skeleton</div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">- of events (steps during the analysis)</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">+ of events </span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">Otherwise, it's hard to read.</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); "><br></span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">- a checker to check that file streams are used properly</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">+ a checker that warns about improper use of file stream APIs</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); "><br></span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">- It can also be used to remove data that is no longer needed from the program state.</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">+ It must also be used to remove data that is no longer needed from the program state.</span></div><div><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); "><br></span></div><div>+ <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1check_1_1PreCall.html" style="line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">PreCall</a><span style="color: rgb(34, 34, 34); line-height: 19px; text-align: left; background-color: rgb(255, 255, 255); ">: Before each function call.</span></div><div style="text-align: left;"><font color="#222222"><span style="line-height: 19px;">I do not like the structure of this description. Specifically, "Before each function call." is not a proper sentence.</span></font></div><div><span style="text-align: left; background-color: rgb(255, 255, 255); "><font color="#222222"><span style="line-height: 19px;"><br></span></font></span></div><div><span style="text-align: left; background-color: rgb(255, 255, 255); "><font color="#222222"><span style="line-height: 19px;">Would be great if we could remove some whitespace from the code snippet; it looks very sparse.</span></font></span></div><div style="text-align: left;"><br></div><div style="text-align: left;">---- Bug Reports</div><div style="text-align: left;"><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); ">- so that it can be output. </span></div><div style="text-align: left;">+ <span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; ">so that it can be displayed</span></div><div style="text-align: left;"><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; "><br></span></div><div style="text-align: left;"><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; ">- Where the bug is</span><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; ">.</span><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; "> </span></div><div style="text-align: left;"><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); ">+ Context of the bug.</span></div><div style="text-align: left;"><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); ">(Not sure it's much better, but it is a noun as the rest of parameter descriptions)</span></div><div style="text-align: left;"><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); "><br></span></div><div style="text-align: left;"><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); ">+ and the program's state when this location is reached. This is in the form on an </span><tt style="background-color: rgb(255, 255, 255); ">ExplodedNode</tt><span style="color: rgb(34, 34, 34); line-height: 19px; background-color: rgb(255, 255, 255); ">.</span></div><div style="text-align: left;"><font color="#222222"><span style="line-height: 19px;">Let's just say node in the ExplodedGraph, in which the error is reported. </span></font></div><div style="text-align: left;"><font color="#222222"><span style="line-height: 19px;"><br></span></font></div><div style="text-align: left;"><span style="line-height: 18px; background-color: rgb(255, 255, 255); ">addTransition should be a link</span></div><div style="text-align: left;"><span style="line-height: 18px; background-color: rgb(255, 255, 255); ">Also, addTransition always has arguments.</span></div><div style="text-align: left;"><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; "><br></span></div><div style="text-align: left;"><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; ">When describing the difference between sinks and regular nodes used for error reporting, I'd mention that a sink is generated when continuing the exploration of the path after the error does not make sense, as the program is in an invalid state. For example, a null pointer dereference uses a sink, while leak does not.</span></div><div style="text-align: left;"><span style="background-color: rgb(255, 255, 255); color: rgb(34, 34, 34); line-height: 19px; ">----</span></div><div style="text-align: left;">I think the current flow does not make much sense anymore. For example, "Idea for a Checker" should go before the sections you've added. I think the following order would be best:</div><div style="text-align: left;"><br></div><div>Getting Started</div><div>Static Analyzer Overview</div><div> Interaction with Checkers</div><div>Idea for a Checker</div><div>Checker Registration</div><div>Checker Skeleton</div><div>Custom Program States</div><div>Representing Values // With added introduction saying that we are going to store info about the values we are observing into the state..</div><div>Bug Reports</div><div>..</div><div><br></div><div>What do you think? I don't mind working on restructuring myself after this content goes in..</div><div><br></div><div>Thanks!</div><div>Anna.</div><div><br></div><div><div>On Mar 24, 2013, at 5:49 PM, Sam Handler <<a href="mailto:samuel.handler+cfedev@gmail.com">samuel.handler+cfedev@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite">Hello all,<br><br>Several months ago, I posted a tutorial about developing a plugin for the Analyzer. After some discussion, it was decided that parts of the tutorial should be integrated into the existing Checker Development Manual.<br>
<br>I've finally had time to complete the majority of this work. Attached is a patch that contains the changes to date. This adds the following information:<br> - Custom Program States<br> - Checker Skeleton<br> - Bug Reports<br>
- Additional sources of information<br><br>I also cleaned up the table of contents a bit, and fixed a incorrect </a> tag.<br><br>There are still some other parts that I am looking at adding, most
notably a description of how the Analyzer processes through a function,
building the program state (I had an example of this in the original
tutorial, but I now think it will need to be completely rewritten). Since I'm not sure how long these additional sections will take, I want to get the ball rolling on getting these changes reviewed and merged.<br><br>
--Sam<br clear="all">
<br>-- <br>===============================================================================<br>All opinions expressed in posts from this account are entirely my own, and not<br>those of any present or former employer. Furthermore, I assert that all works<br>
contributed to the Clang project (1) were developed using no equipment,<br>supplies, facility or trade secrets of any such employer, (2) were developed<br>entirely on my own time, and (3) do not result from any work performed for any<br>
such employer.<br><br>
<span><checker_dev_manual.diff></span>_______________________________________________<br>cfe-dev mailing list<br><a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br><a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br></blockquote></div><br></body></html>