Delete support for deprecated "-- # ..."-style haddock options

A long time ago, you could use `"-- # <haddock options>"` to mean that
`<haddock options.` should be passed to `haddock`. Since 2007
(03d8585e0940e28e024548654fe3505685aca94f), using `OPTIONS_HADDOCK` is
the preferred way to do this.

Why is ok to remove support for "-- # .."?

* It is not mentioned in the Haddock user's guide, nor are there any
  tests that use it.

* Ever since 2011 (b3e30449aa6d6eaa978eb3c7447ca85985d9d251), it doesn't
  actually work anymore. The function `getOptionsFromFile` uses
  `gopt_unset dflags Opt_Haddock` for other reasons, so even when
  running ghc with `--haddock`, the following rule always fires when the
  lexer sees "-- # ..", and it gets treated as a normal comment:

```
    -- Next, match Haddock comments if no -haddock flag
    "-- " [$docsym \#] .* / { ifExtension (not . haddockEnabled) } { lineCommentToken }
```

Reviewed by: bgamari

Differential Revision: https://phabricator.haskell.org/D1932

diff --git a/compiler/main/HeaderInfo.hs b/compiler/main/HeaderInfo.hs
index 3eef327..600b22c 100644 (file)
--- a/compiler/main/HeaderInfo.hs
+++ b/compiler/main/HeaderInfo.hs
@@ -251,10 +251,6 @@ getOptions' dflags toks
               = map (L (getLoc open)) ["-haddock-opts", removeSpaces str]
                 ++ parseToks xs
           parseToks (open:xs)
-              | ITdocOptionsOld str <- getToken open
-              = map (L (getLoc open)) ["-haddock-opts", removeSpaces str]
-                ++ parseToks xs
-          parseToks (open:xs)
               | ITlanguage_prag <- getToken open
               = parseLanguage xs
           parseToks (comment:xs) -- Skip over comments

diff --git a/compiler/parser/ApiAnnotation.hs b/compiler/parser/ApiAnnotation.hs
index 73490e4..6d08b00 100644 (file)
--- a/compiler/parser/ApiAnnotation.hs
+++ b/compiler/parser/ApiAnnotation.hs
@@ -292,7 +292,6 @@ data AnnotationComment =
   | AnnDocCommentNamed String     -- ^ something beginning '-- $'
   | AnnDocSection      Int String -- ^ a section heading
   | AnnDocOptions      String     -- ^ doc options (prune, ignore-exports, etc)
-  | AnnDocOptionsOld   String     -- ^ doc options declared "-- # ..."-style
   | AnnLineComment     String     -- ^ comment starting by "--"
   | AnnBlockComment    String     -- ^ comment in {- -}
     deriving (Eq, Ord, Data, Typeable, Show)

diff --git a/compiler/parser/Lexer.x b/compiler/parser/Lexer.x
index 7067fe0..719d886 100644 (file)
--- a/compiler/parser/Lexer.x
+++ b/compiler/parser/Lexer.x
@@ -228,12 +228,12 @@ $tab          { warnTab }
 -- space followed by a Haddock comment symbol (docsym) (in which case we'd
 -- have a Haddock comment). The rules then munch the rest of the line.
 
-"-- " ~[$docsym \#] .* { lineCommentToken }
+"-- " ~$docsym .* { lineCommentToken }
 "--" [^$symbol \ ] .* { lineCommentToken }
 
 -- Next, match Haddock comments if no -haddock flag
 
-"-- " [$docsym \#] .* / { ifExtension (not . haddockEnabled) } { lineCommentToken }
+"-- " $docsym .* / { ifExtension (not . haddockEnabled) } { lineCommentToken }
 
 -- Now, when we've matched comments that begin with 2 dashes and continue
 -- with a different character, we need to match comments that begin with three
@@ -334,8 +334,6 @@ $tab          { warnTab }
 <option_prags> {
   "{-#"  $whitechar* $pragmachar+ / { known_pragma fileHeaderPrags }
                                    { dispatch_pragmas fileHeaderPrags }
-
-  "-- #"                           { multiline_doc_comment }
 }
 
 <0> {
@@ -344,10 +342,6 @@ $tab          { warnTab }
                      { nested_comment lexToken }
 }
 
-<0> {
-  "-- #" .* { lineCommentToken }
-}
-
 <0,option_prags> {
   "{-#"  { warnThen Opt_WarnUnrecognisedPragmas (text "Unrecognised pragma")
                     (nested_comment lexToken) }
@@ -732,7 +726,6 @@ data Token
   | ITdocCommentNamed String     -- something beginning '-- $'
   | ITdocSection      Int String -- a section heading
   | ITdocOptions      String     -- doc options (prune, ignore-exports, etc)
-  | ITdocOptionsOld   String     -- doc options declared "-- # ..."-style
   | ITlineComment     String     -- comment starting by "--"
   | ITblockComment    String     -- comment in {- -}
 
@@ -1063,7 +1056,6 @@ withLexedDocType lexDocComment = do
     '^' -> lexDocComment input ITdocCommentPrev False
     '$' -> lexDocComment input ITdocCommentNamed True
     '*' -> lexDocSection 1 input
-    '#' -> lexDocComment input ITdocOptionsOld False
     _ -> panic "withLexedDocType: Bad doc type"
  where
     lexDocSection n input = case alexGetChar' input of
@@ -2757,7 +2749,6 @@ commentToAnnotation (L l (ITdocCommentPrev s))  = L l (AnnDocCommentPrev s)
 commentToAnnotation (L l (ITdocCommentNamed s)) = L l (AnnDocCommentNamed s)
 commentToAnnotation (L l (ITdocSection n s))    = L l (AnnDocSection n s)
 commentToAnnotation (L l (ITdocOptions s))      = L l (AnnDocOptions s)
-commentToAnnotation (L l (ITdocOptionsOld s))   = L l (AnnDocOptionsOld s)
 commentToAnnotation (L l (ITlineComment s))     = L l (AnnLineComment s)
 commentToAnnotation (L l (ITblockComment s))    = L l (AnnBlockComment s)
 commentToAnnotation _                           = panic "commentToAnnotation"
@@ -2775,7 +2766,6 @@ isDocComment (ITdocCommentPrev  _)   = True
 isDocComment (ITdocCommentNamed _)   = True
 isDocComment (ITdocSection      _ _) = True
 isDocComment (ITdocOptions      _)   = True
-isDocComment (ITdocOptionsOld   _)   = True
 isDocComment _ = False
 
 {- Note [Warnings in code generated by Alex]