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

newer
Constraint error related to type...

older
Small Int and Char closures in GHCi

Herbert Valerio Riedel

4 Sep 2012 4 Sep '12

6:56 a.m.

Hello Haskellers, I've been wondering whether it might be useful to add a feature to Haddock similar to what can be found in other API documentation systems, specifically an optional parseable "since"-attribute, declaring the last package version when the associated definition/symbol was introduced or its semantics modified. Beyond giving a uniform/standard representation for this kind of information (e.g. if Haddock would render this information in a distinctive style suitable to give a visual hint for locating this information easily), this information could be used to generate an automated changelog entry (at least for the current package version), listing all definitions added or modified with the current version. Another application I could thinkg of would be to find the lowest version of a package supporting the currently used API from it (given the currently known-to-work package-version and a list of currently used symbols from that package). 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?

Show replies by date

Greg Weber

4 Sep 4 Sep

10:11 a.m.

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

a lot of packages are doing this already, would be nice to formalize it On Tue, Sep 4, 2012 at 3:56 AM, Herbert Valerio Riedel wrote:

...

Hello Haskellers,

I've been wondering whether it might be useful to add a feature to Haddock similar to what can be found in other API documentation systems, specifically an optional parseable "since"-attribute, declaring the last package version when the associated definition/symbol was introduced or its semantics modified.

Beyond giving a uniform/standard representation for this kind of information (e.g. if Haddock would render this information in a distinctive style suitable to give a visual hint for locating this information easily), this information could be used to generate an automated changelog entry (at least for the current package version), listing all definitions added or modified with the current version.

Another application I could thinkg of would be to find the lowest version of a package supporting the currently used API from it (given the currently known-to-work package-version and a list of currently used symbols from that package).

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?

_______________________________________________ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users

Bryan O'Sullivan

1:18 p.m.

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

On Tue, Sep 4, 2012 at 3:56 AM, Herbert Valerio Riedel wrote:

...

I've been wondering whether it might be useful to add a feature to Haddock similar to what can be found in other API documentation systems, specifically an optional parseable "since"-attribute, declaring the last package version when the associated definition/symbol was introduced or its semantics modified.

I think it would be very useful. We don't have any way of specifying identifier-level attributes right now that I know of, and such a capability would be helpful beyond just this use, too.

Herbert Valerio Riedel

5:29 p.m.

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

"Bryan O'Sullivan" writes:

...

I think it would be very useful. We don't have any way of specifying identifier-level attributes right now that I know of, and such a capability would be helpful beyond just this use, too.

...what other use-cases for identifier-level attributes do you have in mind?

Johan Tibell

6:39 p.m.

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

On Tue, Sep 4, 2012 at 2:29 PM, Herbert Valerio Riedel wrote:

...

"Bryan O'Sullivan" writes:

...
I think it would be very useful. We don't have any way of specifying identifier-level attributes right now that I know of, and such a capability would be helpful beyond just this use, too.

...what other use-cases for identifier-level attributes do you have in mind?

Have a look at the Javadoc specification from ideas. Things like @see seems useful. -- Johan

Bardur Arantsson

1:26 p.m.

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

On 09/04/2012 12:56 PM, Herbert Valerio Riedel wrote:

...

Hello Haskellers,

I've been wondering whether it might be useful to add a feature to Haddock similar to what can be found in other API documentation systems, specifically an optional parseable "since"-attribute, declaring the last package version when the associated definition/symbol was introduced or its semantics modified.

Evan Laforge

1:38 p.m.

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

...

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 recently stumbled across a document system that does something like this: http://libgit2.github.com/libgit2/#HEAD New functions are green, changed ones are orange, and the functions themselves have a version history. You can switch versions within the function, or globally with the version box in the upper right. It's pretty neat. I don't know how it works but I imagine it uses the git history.

Herbert Valerio Riedel

5 Sep 5 Sep

4:10 a.m.

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

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)

Simon Marlow

11:36 a.m.

New subject: 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

Roman Cheplyaka

1:22 p.m.

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

* Simon Marlow [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/

4641

Age (days ago)

4642

Last active (days ago)

List overview

Download

9 comments

8 participants

participants (8)

Bardur Arantsson
Bryan O'Sullivan
Evan Laforge
Greg Weber
Herbert Valerio Riedel
Johan Tibell
Roman Cheplyaka
Simon Marlow