Code documentation

[ndanger000]

Please document functions, classes, etc. This code is part of your thesis, and is likely to live on past your thesis submission. So I need to be able to read it and be confident that it is correct. And I can't be confident it is correct if I don't know what it is supposed to be doing 😄

[ndanner-wesleyancs]

@tim-stephenson

This is getting better (as of 0eec442), but could still use a bit of work. Remember, the point of documenting a function is to provide the client with enough information that they can use the result without looking at the implementation.

So, e.g., consider the documentation you have for analyzers.analyzer.Analyzer.get_analysis_results: "get the analysis results." I know it returns a List [ Tuple[str, str]]. But what does an item (s, t) in that list represent? I suspect you need something like:

• Documentation for Analysis to the effect that an Analysis object represents an algorithm for classifying (site, script) pairs that occur in an OpenWPM crawl database; or maybe simultaneously more abstractly and more precisely, an analysis object represents a function analyze : Tuple [str, str] -> bool, where the argument is intended to be a (site, script) pair that occurs in an OpenWPM crawl databse.
• Then get_analysis_results returns those (site, script) pairs in the crawl database such that analyze(site, script) = True.