[Haddock] DocTest integration into Haddock

[David Waern]

2010/8/8 Simon Hengel <simon.hengel at wiktory.org>:
> A patch is attached.
>
> Some notes on the patch:
>
>  * 'createInterfaces'' will fail with usage information, if unrecognized
>   flags are passed in.  A cleaner solution may be, to tighten the type
>   of flags, like:
>
>     createInterfaces'
>       :: [CreateInterfacesFlags] -- ^ Flags, that control 'Interface'
>                                  -- creation
>       -> [String]                -- ^ A list of file or module names
>       -> IO [Interface]
>
>   This would also result in more brief documentation for
>   'createInterfaces''.  However it would require some refactoring.
>
>   For DocTest the current behavior is just fine, as I can do
>   whitelisting on flags.  Do you think it is ok, to keep the current
>   behavior?

Sorry once again for taking so long.

I've applied the patch and done some refactoring after you got me
thinking about the names of things. I renamed the original
createInterfaces into processModules as it actually returns not only
Interfaces but also the linking environment. Your function is now:

  createInterfaces :: [Flag] -> [String] -> IO [Interface]

I prefer Flag over raw command line strings since reader of the
documentation can go to the Flag type to see which flags are actually
accepted. We still have the issue of many flags that don't apply to
this function.

>  * DocTest does not require dumping of interfaces, so we could move that
>   to 'main' and document 'createInterfaces'' accordingly.  What is your
>   preference here?

Yes, I've done that.

>  * Please let me know, if you have nicer names for createInterfaces' and
>   readPackagesAndCreateInterfaces.  We already have a (not exported)
>   helper function called createInterfaces' in module
>   "Haddock.Interface", is that an issue?

I changed the latter to readPackagesAndProcessModules, and had it
return the link environment as well.

Thanks for the patch and for factoring out stuff in Main, it improved
the readability of the code.

David