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

[Roman Cheplyaka]

* Simon Marlow <marlowsd at gmail.com> [2012-09-05 16:36:01+0100]
> 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 such a note belongs to the changelog rather than the
documentation. Majority of documentation readers do not care how the
function used to work; they care how it works now and which versions of
the package to put as a dependency.

If the "since" attribute respects semantic changes, a tool can be
written that would automatically give you version constraints that you
can put into the .cabal file.

OTOH, people who already use a package may not look into the docs often;
however, it is reasonable to expect them to read the changelog when
upgrading their software to use newer versions of dependencies.

To summarise, I'm for manual and semantic "since" attribute, although
it would be nice to have a tool that would help authors to fill this
attribute as you described.

-- 
Roman I. Cheplyaka :: http://ro-che.info/