Ticket #29 (closed enhancement: fixed)

Opened 5 years ago

Last modified 3 years ago

Comments on instance declarations

Reported by: waern Owned by:
Priority: critical Milestone:
Version: Keywords:
Cc: haddock@…, jmg@…, SamB, nogin

Description (last modified by waern) (diff)

More and more people really want this.

Change History

  Changed 4 years ago by ross

This is a frustrating omission. When instances are listed in the documentation of a class or type constructor, there's blank space on the right, when there could a documentation comment attached to the instance declaration.

  Changed 4 years ago by waern

You are right, and it should be very easy to add since the comments are there in the abstract syntax and just need to be displayed.

follow-up: ↓ 4   Changed 4 years ago by ross

It would also be useful to generate a boilerplate comment for derived instances, as then users could work out exactly what they mean.

in reply to: ↑ 3 ; follow-up: ↓ 5   Changed 4 years ago by waern

Replying to ross:

It would also be useful to generate a boilerplate comment for derived instances, as then users could work out exactly what they mean.

Do you mean a comment saying that the instance has been automatically derived, or something more sophisticated?

in reply to: ↑ 4   Changed 4 years ago by anonymous

Replying to waern:

Replying to ross:

It would also be useful to generate a boilerplate comment for derived instances, as then users could work out exactly what they mean.

Do you mean a comment saying that the instance has been automatically derived, or something more sophisticated?

Some fixed phrase would be enough. If the user knows the instance is derived, they can figure out what it does.

  Changed 4 years ago by anonymous

  • cc haddock@… added

  Changed 4 years ago by jmg@…

Wouldn't it be even nicer to be able to (optionally) comment not only the instance as a whole but also the functions of the instance? There could also be a link to the documentation of the function in the class declaration.

  Changed 4 years ago by anonymous

  • cc jmg@… added

  Changed 4 years ago by waern

  • priority changed from minor to major

  Changed 4 years ago by SamB

What should the output look like?

  Changed 4 years ago by SamB

Hey ... how in the world are we going to get instances into our export lists, anyway?

  Changed 4 years ago by SamB

  • cc SamB added

  Changed 4 years ago by nogin

  • cc nogin added

  Changed 4 years ago by waern

  • priority changed from major to critical
  • description modified (diff)

  Changed 3 years ago by waern

  • status changed from new to closed
  • resolution set to fixed

Implemented by this patch: 

 Comments on instances
 David Waern <david.waern@gmail.com>**20091124205549
 
 Implementing this was a little trickier than I thought, since we need to match
 up instances from the renamed syntax with instances represented by
 InstEnv.Instance. This is due to the current design of Haddock, which matches
 comments with declarations from the renamed syntax, while getting the list of
 instances of a class/family directly using the GHC API.
 
 - Works for class instances only (Haddock has no support for type family
   instances yet)
 - The comments are rendered to the right of the instance head in the HTML output
 - No change to the .haddock file format
 - Works for normal user-written instances only. No comments are added on
   derived or TH-generated instances

What remains is:

  • Comments on methods (needs more detailed instance documenation).
  • Auto-generated comments on derived/TH-generated instances.

I'm closing this ticket and opening separate tickets for those two tasks.

Note: See TracTickets for help on using tickets.