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

On 05/09/2012 09:10, Herbert Valerio Riedel wrote:

Evan Laforge 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