Opened 4 years ago

Last modified 3 weeks ago

#8822 new feature request

Allow -- ^ Haddock syntax on record constructors

Reported by: Fuuzetsu Owned by:
Priority: normal Milestone:
Component: Compiler (Parser) Version: 7.9
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: None/Unknown Test Case:
Blocked By: Blocking:
Related Tickets: #9770, #12050 Differential Rev(s): https://phabricator.haskell.org/D4094
Wiki Page:

Description

Original ticket is on Haddock Trac here which I'm opening here as it requires lexer/parser changes.

The idea is that given something like

-- | A tree with labeled internal nodes
data Tree =
    Empty                -- ^ Leaf
  | Branch               -- ^ Internal node
    { label :: a         -- ^ Node label
    , subtrees :: [Tree] -- ^ List of subtrees
    }

we'd like it to parse as the user would expect instead of failing. We're currently forced to do something like

-- | A tree with labeled internal nodes
data Tree =
    Empty                -- ^ Leaf
  | -- | Internal node
    Branch
    { label :: a         -- ^ Node label
    , subtrees :: [Tree] -- ^ List of subtrees
    }

which is quite ugly. I can't think of a reason why the first form wouldn't be allowed.

Change History (7)

comment:1 Changed 4 years ago by goldfire

difficulty: UnknownModerate (less than a day)

I took a look at this, and it requires more happy-fu than I've got at the moment. Suppose that we implemented parsing as requested, Then, the problem is that the parser gets mightily confused when it sees

  data Foo = Bar  -- ^ urk

What should it expect next? A | and another constructor? Or a { and a list of fields? Given the current way constructors are parsed (as types, to allow the possibility of infix constructors), there's not an easy way to restructure things to answer this question (that I can see).

On the plus side, I think that solving this problem would make it easier to implement something I've wanted: the ability to annotate individual constructor arguments, like so:

data Foo = Bar Int    -- ^ urk
               Double -- ^ blah

which would currently be difficult to parse. If someone wants to restructure this section of the parser, please go for it! :)

comment:2 Changed 3 years ago by thomie

comment:3 Changed 18 months ago by thomie

comment:4 Changed 17 months ago by erikd

Found an example very close to @goldfire's example above:

data Command =
     -- | Run a job.
    Run
      String -- ^ Name.
      Bool -- ^ Fast.
      [String] -- ^ Run arguments.
  | -- | Stop a job.
    Stop
      Int -- ^ Job number.

comment:5 Changed 5 weeks ago by harpocrates

I have a patch that implements both the initial idea and the the suggestion in comment:4. I'll link to it shortly. The only unpleasantness here is that we probably want to maintain backwards compatibility.

For that, I decided to lift doc comments on the last field of the constructor to the constructor, provided there are no other doc comments either on the constructor or any of the other fields. This ensures that existing docs will all still parse the same way.

 data Foo
   = Bar Int String  -- ^ doc on `Bar` constructor

   | Baz             -- ^ doc on the `Baz` constructor
       Int           -- ^ doc on the `Int` field of `Baz`
       String        -- ^ doc on the `String` field of `Baz`

   | Int :+ String   -- ^ doc on the `:+` constructor

   | Int             -- ^ doc on the `Int` field of the `:*` constructor
       :*            -- ^ doc on the `:*` constructor
     String          -- ^ doc on the `String` field of the `:*` constructor

   | Boo { x :: () } -- ^ doc on the `Boo` record constructor

   | Boa             -- ^ doc on the `Boa` record constructor
       { y :: () } 

The patch also adds support for doc comments on GADT constructor arguments.

data Foo where
  Foo :: Int    -- ^ `Int` field of `Foo`
      -> String -- ^ `String` field of `Foo`
      -> Foo

comment:6 Changed 5 weeks ago by harpocrates

Here is the patch I mentioned in comment:5. https://phabricator.haskell.org/D4094

comment:7 Changed 3 weeks ago by harpocrates

Differential Rev(s): https://phabricator.haskell.org/D4094
Note: See TracTickets for help on using tickets.