Multiline comments in data declaration

[deepakjois]

Here is a code sample. for data declarations with comments that span multiple lines to fit into the 80 char line width requirement.

data Turtle = Turtle
  { isPenDown  :: Bool            -- ^ State of the pen. @False@ means that
                                  -- turtle movements will not draw anything
  , penPos     :: P2              -- ^ Current position. This is updated
                                  -- everytime the turtle moves
  , heading    :: Deg             -- ^ Orientation of the turtle in 2D space,
                                  -- given in degrees
  , currTrail  :: (P2, Trail R2)  -- ^ Path traversed by the turtle so far,
                                  -- without any style or pen attributes
                                  -- changing
  , currStyle  :: PenStyle        -- ^ Current style of the pen
  , paths      :: [TurtlePath]    -- ^ List of paths along with style
                                  -- information, traversed by the turtle
                                  -- previously
  }

Any suggestions on how to make it more readable? Maybe have an an empty line after each field?

[jaspervdj]

When you have long comments for the fields of a datatype, I find the -- | style far more readable than the -- ^ style: you can use most of the line, which is very useful if you need comment formatting (e.g. code example, list). This example would become:

data Turtle = Turtle
    { -- | State of the pen. @False@ means that turtle movements will not draw
      -- anything
      isPenDown  :: Bool
    , -- | Current position. This is updated everytime the turtle moves
      penPos     :: P2  
    , -- | Orientation of the turtle in 2D space, given in degrees
      heading    :: Deg
    , -- | Path traversed by the turtle so far, without any style or pen
      -- attributes changing
      currTrail  :: (P2, Trail R2)
    , -- | Current style of the pen
      currStyle  :: PenStyle        
    , -- | List of paths along with style information, traversed by the turtle
      -- previously
      paths      :: [TurtlePath]    
    }

Optionally with an empty line after each field.

[Mikolaj]

You can also do

data Turtle = Turtle
  { isPenDown  :: Bool            
      -- ^ state of the pen; @False@ means that turtle movements 
      --   will not draw anything
  , penPos     :: P2              -- ^ current position

which can be used to mix short comments with long comments (looks not so very bad if the long comments are rare).

[deepakjois]

For the purpose of establishing a convention, I prefer @jaspervdj's version. Is it something worth documenting in the style guide?

[tibbe]

I prefer @jaspervdj's version as well. Documented in 74d065c73334d2dc1bfe6f5d8eadfa8ff09471c1.