Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#1903 closed proposal (wontfix)

Meta-Proposal: Documentation should be required to say when exports were introduced

Reported by: igloo Owned by:
Priority: normal Milestone: Not GHC
Component: Compiler Version: 6.8.1
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Difficulty: Unknown
Test Case: Blocked By:
Blocking: Related Tickets:

Description

One of the nice things about, for example, PHP is that if you look at the documentation for one of its functions, e.g.:
http://www.php.net/manual/en/function.file-get-contents.php,
it tells you that file_get_contents is available in PHP >= 4.3.0.

I propose that all exports in Haskell libraries should be required to have such a thing in their haddock documentation. For the current code we could either give the current versions as the date of introduction, or do some digging and put precise data in.

Initial deadline: 1 December 2007.

Change History (4)

comment:1 Changed 6 years ago by simonmar

I'd like to do this automatically with tool support. For example, we can retain the .haddock files for previous versions of a package, and Haddock can infer when particular entities were introduced, and add the appropriate annotations. IIRC Hoogle has some functionality that could be used for this too.

Related to this is the need to compare APIs for determining whether version bumps are necessary. We should therefore have a way to dump an API in a machine-readable format for use by Haddock and other tools.

comment:2 Changed 6 years ago by igloo

  • Resolution set to wontfix
  • Status changed from new to closed

Consensus was to wait for tool support

comment:3 Changed 6 years ago by simonmar

  • Architecture changed from Unknown to Unknown/Multiple

comment:4 Changed 6 years ago by simonmar

  • Operating System changed from Unknown to Unknown/Multiple
Note: See TracTickets for help on using tickets.