[libTooling] Add a comment about comment parsing to getAssociatedRange.

[jacobsa]

Summary

It took me multiple hours of debugging plus asking an expert for help to
figure out why this function didn't do what it promised to do. It turns
out there is a flag that needs to be set. Document this, in an attempt
to save the next person the surprise.

[ymandel]

Thank you!

[ymandel]

clang/include/clang/Tooling/Transformer/SourceCode.h

47

[jacobsa]

Address formatting comment from ymandel.

[jacobsa]

@ymandel: thanks! Are you able to commit?

[ymandel]

sure

clang/include/clang/Tooling/Transformer/SourceCode.h

return maybeExtendRange(CharSourceRange::getTokenRange(Node.getSourceRange()),
                           Next, Context);
 }
 
 /// Returns the logical source range of the node extended to include associated
 /// comments and whitespace before and after the node, and associated
 /// terminators. The returned range consists of file locations, if valid file
 /// locations can be found for the associated content; otherwise, an invalid
 /// range is returned.
+///
+/// Note that parsing comments is disabled by default. In order to select a
+/// range containing associated comments, you may need to invoke the tool with
+/// `-fparse-all-comments`.
 CharSourceRange getAssociatedRange(const Decl &D, ASTContext &Context);
 
 /// Returns the source-code text in the specified range.
 StringRef getText(CharSourceRange Range, const ASTContext &Context);
 
 /// Returns the source-code text corresponding to \p Node.
 template <typename T>
 StringRef getText(const T &Node, const ASTContext &Context) {