[Haskell-cafe] Formatting function types

[Larry Evans]

On 12/30/10 08:17, Henning Thielemann wrote:
>
> On Thu, 30 Dec 2010, Lauri Alanko wrote:
>
>> Even nowadays, Haddock deliberately generates the following layout for
>> long function types:
>>
>> openTempFile
>>    :: FilePath
>>    -> String
>>    -> IO (FilePath, Handle)
>>
>> The layout draws special attention to the first argument type, whereas
>> the other argument types are indistinguishable from the return
>> type.

Lauri, I assume then that you want to draw special attention to
the return type instead of the first argument type.

>>The following is much clearer:
>>
>> openTempFile ::
>>    FilePath ->
>>    String ->
>>    IO (FilePath, Handle)
>>
>> (Possibly with the arrows aligned.)

So, with this "operator postfix" formatting, the special
attention to the return type is achieved by *not* suffixing it
with ->.  However, to see that it's not suffixed with ->, your
eyes have to scan to the right for the whole line until you don't
find the ->.  Oh, but wait, if the return type is an elaborate
type expression, that takes up more than say, 60 spaces, then I
would want to format it over more than one line.  Yes, that would
be rare, but possible.  Now you'd have to scan not 1 but 2 lines
to find (or rather not find) the ->. OK, but then why not just
find the last argument and forget about finding the missing
postfix ->?  Well, in that case, the "operator prefix" formatting
would serve just as well.

The attachment contains ret_{post,pre} declaration which
provide a concrete example.  Maybe I'm just used to the prefix
formatting, but I do find ret_pre easier to read than the
ret_post.  I find it more readable because I just have to search,
in a given column, for the last ->, and then I know the following
is the return type.

>
> +1
>
>
> GHC also formats type signatures in errors and warnings in the
> misleading way.
>
> In case of Haddock comments I understand that the comment must be close
> to the argument type.

Henning, I guess you're saying Haddock puts -> first on the line
in order to make the comment as close as possible to the argument type.

> That is
>
> openTempFile
>    FilePath -- ^ filename, of course  ->
>    String ->
>    IO (FilePath, Handle)
>
> would not work. But {- ^ filename -} would work.

So, Haddock would format this(after adding comments for other args) as:

[1]:
  openTempFile
     :: FilePath -- ^ filename, of course
     -> String -- ^ comment for 2nd arg.
     -> IO (FilePath, Handle) -- ^ comment for 3ird arg

However, you and Lauri would prefer (IIUC):

[2]:
  openTempFile::
     FilePath {- ^ filename, of course -} ->
     String {- ^ comment for 2nd arg. -} ->
     IO (FilePath, Handle) -- ^ comment for 3ird arg

or, to retain the same comment types:

[3]:
  openTempFile::
     FilePath -- ^ filename, of course
     ->
     String -- ^ comment for 2nd arg.
     ->
     IO (FilePath, Handle) -- ^ comment for 3ird arg

OK, but then there's more vertical space used, so maybe [2]
is better; however, [2] separates the operator, -> from it's
operands by the the comment.  Maybe you could justify this by
saying the operator is not important for readability; however,
in my reply to Lauri, I indicated it was easier to find the
last argument if the operators were prefixed, as was illustrated
by the ret_{post,pre} declarations in the attachment.  Likewise,
I find it easier to find the last argument with [1] rather than
either [2] or [3].

-regards,
 Larry



-------------- next part --------------
A non-text attachment was scrubbed...
Name: Format.hs
Type: text/x-haskell
Size: 559 bytes
Desc: not available
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20101230/56bfaf0e/attachment.hs>