[docs] PCH usage documentation update

[ivanmurashko]

Summary

The documentation has an incorrect example of PCH files usage via -include option. The possibility has not been available since llvm-svn: 174385.

[ivanmurashko]

Minor changes at the doc

[aaron.ballman]

LGTM, thanks for improving the docs!

[ivanmurashko]

Some clarifications for the direct include example were added

[tahonermann]

Reopening for further discussion or clarification.

The changes appear to suggest that a PCH file won't be implicitly used when an explicit include for the corresponding header is made via the -include option, but that is not correct.

$ cat t.h
const int i = 0;
$ cat t.c
int g = i;
$ clang t.h
$ ls -1
t.c
t.h
t.h.gch
$ clang -c -I. -include t.h t.c
$ touch t.h
$ clang -c -I. -include t.h t.c
fatal error: file '/iusers/thonerma/tmp/pch/t.h' has been modified since the precompiled header 't.h.gch' was built: mtime changed
note: please rebuild precompiled header 't.h.gch'
1 error generated.

If the ability to include a PCH file via -include is intentional behavior (as I have always believed it to be), then I think the documentation should demonstrate both the -include and -include-pch methods of using a PCH file.

Please note that gcc also supports implicit use of a PCH file via its -include option.

[tahonermann]

Re-closing since this review has already landed.

@akyrtzi, did you see my last comment? If I don't hear back from you, I'll submit a new doc change that covers both forms of PCH use.

clang/docs/UsersManual.rst

 .. code-block:: console
 
   $ gcc -x c-header test.h -o test.h.gch
   $ clang -x c-header test.h -o test.h.pch
 
 Using a PCH File
 ^^^^^^^^^^^^^^^^
 
-A PCH file can then be used as a prefix header when a :option:`-include`
+A PCH file can then be used as a prefix header when a :option:`-include-pch`
 option is passed to ``clang``:
 
 .. code-block:: console
 
-  $ clang -include test.h test.c -o test
+  $ clang -include-pch test.h.pch test.c -o test
 
-The ``clang`` driver will first check if a PCH file for ``test.h`` is
+The ``clang`` driver will check if the PCH file ``test.h.pch`` is
 available; if so, the contents of ``test.h`` (and the files it includes)
-will be processed from the PCH file. Otherwise, Clang falls back to
-directly processing the content of ``test.h``. This mirrors the behavior
-of GCC.
+will be processed from the PCH file. Otherwise, Clang will report an error.
 
 .. note::
 
   Clang does *not* automatically use PCH files for headers that are directly
-  included within a source file. For example:
+  included within a source file or indirectly via :option:`-include`.
+  For example:
 
   .. code-block:: console
 
     $ clang -x c-header test.h -o test.h.pch
     $ cat test.c
     #include "test.h"
     $ clang test.c -o test
 
   In this example, ``clang`` will not automatically use the PCH file for
   ``test.h`` since ``test.h`` was included directly in the source file and not
-  specified on the command line using :option:`-include`.
+  specified on the command line using :option:`-include-pch`.
 
 Relocatable PCH Files
 ^^^^^^^^^^^^^^^^^^^^^
 
 It is sometimes necessary to build a precompiled header from headers
 that are not yet in their final, installed locations. For example, one
 might build a precompiled header within the build tree that is then
 meant to be installed alongside the headers. Clang permits the creation