Add docs for --no_fwd_decls

It fits naturally in the WhyIWYU document, which has a discussion on
forward declarations.

1 files changed, 4 insertions, 0 deletions

diff --git a/docs/WhyIWYU.md b/docs/WhyIWYU.md
index 929d614..bd15b0e 100644
--- a/docs/WhyIWYU.md
+++ b/docs/WhyIWYU.md
@@ -45,3 +45,7 @@ The reason for this is simple: if you can replace an `#include` by a forward-dec
 There's a cost to forward-declaring as well: you lose the documentation features mentioned above, that come with `#include` lines.  (A future version of IWYU may mitigate this problem.)  And if a class changes -- for instance, it adds a new default template argument -- you need to change many callsites, not just one.  It is also easier to accidentally violate the [One Definition Rule](http://en.wikipedia.org/wiki/One_Definition_Rule) when all you expose is the name of a class (via a forward declare) rather than the full definition (via an `#include`).
 
 One compromise approach is to use 'forwarding headers', such as `<iosfwd>`.  These forwarding headers could have comments saying where the definition of each forward-declared class is.  Include-what-you-use does not currently support forwarding headers, but may in the future.
+
+Since some coding standards have taken to [discourage forward declarations](https://google.github.io/styleguide/cppguide.html#Forward_Declarations), IWYU has grown a `--no_fwd_decls` mode to embrace this alternative strategy. Where IWYU's default behavior is to minimize the number of include directives, IWYU with `--no_fwd_decls` will attempt to minimize the number of times each type is redeclared. The result is that include directives will always be preferred over local forward declarations, even if it means including a header just for a name-only type declaration.
+
+We still think IWYU's normal policy is preferable for all the reasons above, but if your codebase has a no-forward-declare policy, so does IWYU.