RFC: Adding support for an API-"since"-version-attribute to Haddock?

[Simon Marlow]

On 05/09/2012 09:10, Herbert Valerio Riedel wrote:
> Evan Laforge <qdunkan at gmail.com> writes:
>
>>> Would such an enhancement to Haddock be worthwhile or is it a bad idea?
>>> Has such a proposal come up in the past already? Are there alternative
>>> approaches to consider?
>>
>> It would be even cooler to automatically figure them out from the
>> hackage history.
>
> I don't think this can ever be reliable if it is to detect more than
> mere additions of new functions at the source-level.
>
> Just modifying a function (w/o changing the type-signature) doesn't mean
> its semantics have to change -- could be just refactoring or optimizing
> that lead to the implementation (but not the semantics) changing.
>
> Also, /not/ modifying a function doesn't necessarily mean that its
> semantics are unchanged, as it could be just some semantic change to a
> function outside the function (but depended upon by the function) that
> could cause the function to modify its semantics.
>
> Thus, IMHO it will always require some manual intervention by the
> developer (although it may be surely aided by tools helping with
> analysing the source-code versioning history and pointing out possible
> candidates)

If the semantics of a function changes, then you'll want to note that in 
the documentation for the function, rather than just slapping on a 
"since" attribute.  I think automatically deriving "since" and "changed" 
information from the module interface makes perfect sense, indeed it is 
something we've had on the Haddock todo list for a long time.

You could do it based on the information in the Haddock interface files, 
but of course you need to have the interfaces for all versions 
available.  Perhaps it should be standard practice to check these into 
the repo when doing a release.  In any case it wouldn't be hard to 
generate the Haddock interfaces for old releases of a package from the 
Hackage archives.

Cheers,
	Simon