[PATCH] D22298: [LCG] Update and expand comments to properly document the design motivation, tradeoffs, and constraints.

[Chandler Carruth via llvm-commits]

chandlerc created this revision.
chandlerc added reviewers: sanjoy, hfinkel, dberlin, davidxl, silvas.
chandlerc added a subscriber: llvm-commits.
Herald added a subscriber: mcrosier.

This is essentially attempting to embed the living document parts of
a design document into the doxygen comments for the analysis. I can
separate these docs into a restructured text file, but personally
I prefer keeping it as close to the code as possible.

The first section here outlines the high-level motivation, constraints,
and resulting tradeoffs of the design. These are expressed in the
file-level comment as they don't *directly* pertain to the API itself.

The second section is the class comment that tries to give a more
comprehensive but still high-level description of the implementation
strategy for the design.

This doesn't (yet) update the mutation API comments. I'd like to do that
too, but I think its a bit lower priority and I want to try to draw some
ASCII-art diagrams to go with it which will take a while. I didn't want
the higher level stuff to wait on that.

The only really big section of a traditional design document that isn't
really covered here are detailed discussions of the alternatives
considered. I'm open to suggestions about whether that's really useful,
and where within this it would be useful. My personal inclination is to
discuss status, process, and alternatives in commit logs rather than
code, but I'm happy to talk about other places where such discussion can
live.

Also, thanks to Daniel Jasper who provided a ton of informal review for
me as someone who had no idea what any of this did to make sure I wasn't
assuming too much.

http://reviews.llvm.org/D22298

Files:
  include/llvm/Analysis/LazyCallGraph.h

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D22298.63783.patch
Type: text/x-patch
Size: 12599 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20160713/fc95dc31/attachment.bin>