diff options
| author | Vladislav Zavialov <vlad.z.4096@gmail.com> | 2019-12-05 03:06:40 +0300 |
|---|---|---|
| committer | Vladislav Zavialov <vlad.z.4096@gmail.com> | 2020-07-20 12:10:03 +0300 |
| commit | 4bda699ce3a3f86486409b3f45f1eb761e3b8265 (patch) | |
| tree | e06ebbafa831b6af7c806b4ef77234b8bdbf95e8 /docs/users_guide/using-warnings.rst | |
| parent | c26e81d116a653b5259aeb290fb1e697efe3382a (diff) | |
| download | haskell-wip/haddock-accum.tar.gz | |
Accumulate Haddock comments in P (#17544, #17561, #8944)wip/haddock-accum
Haddock comments are, first and foremost, comments. It's very annoying
to incorporate them into the grammar. We can take advantage of an
important property: adding a Haddock comment does not change the parse
tree in any way other than wrapping some nodes in HsDocTy and the like
(and if it does, that's a bug).
This patch implements the following:
* Accumulate Haddock comments with their locations in the P monad.
This is handled in the lexer.
* After parsing, do a pass over the AST to associate Haddock comments
with AST nodes using location info.
* Report the leftover comments to the user as a warning (-Winvalid-haddock).
Diffstat (limited to 'docs/users_guide/using-warnings.rst')
| -rw-r--r-- | docs/users_guide/using-warnings.rst | 19 |
1 files changed, 19 insertions, 0 deletions
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst index 256d143f45..a83cc6837e 100644 --- a/docs/users_guide/using-warnings.rst +++ b/docs/users_guide/using-warnings.rst @@ -1762,6 +1762,25 @@ of ``-W(no-)*``. You may want to enable this warning on a clean build or enable :ghc-flag:`-fforce-recomp` in order to get reliable results. +.. ghc-flag:: -Winvalid-haddock + :shortdesc: warn when a Haddock comment occurs in an invalid position + :type: dynamic + :category: + + :since: 8.12 + + When the ``-haddock`` option is enabled, GHC collects documentation + comments and associates them with declarations, function arguments, data + constructors, and other syntactic elements. Documentation comments in + invalid positions are discarded:: + + myValue = + -- | Invalid (discarded) comment in an expression + 2 + 2 + + This warning informs you about discarded documentation comments. + It has no effect when :ghc-flag:`-haddock` is disabled. + If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice. It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's sanity, not yours.) |