Comments on instance methods

[ghc-mirror]

Original reporter: david.waern@

We need a more detailed view of instances before we implement this.

[ivanperez-keera]

Well, it would be fantastic to re-visit this, if someone has the time.

Currently, if the class method is not documented, then every explicit export of that method is reported as undocumented.

We care a lot about documentation, and we are trying to achieve 100% documentation on some of our projects. This means we can't make the haddock test mandatory, so someone needs to check if new definitions are undocumented.

For a more concrete example, it's currently biting us here: ivanperez-keera/Yampa#65

[alexbiehl]

Thank you for paging that issue in @ivanperez-keera! This sounds like a sensible thing to do.

Unfortunately I am short on time lately. Would you like to propose a PR? I can guide you if any help is needed.

[ivanperez-keera]

I'm in a similar position myself: I can try it as it is developed, but this sounds non-trivial for someone who is not familiar at all with the internals of haddock. I cannot commit to completing this at the moment :(

How about tagging this with help-wanted?

[alexbiehl]

The change would be big indeed. - Currently no collection of documentation happens for type class instances (see `classDecls`) - Even if we collect docstrings on instance methods. These need to go into their own `Map` in `Interface` as these would overwrite the docs on class methods definition otherwise. - This new mapping has to be added to `InstalledInterface` too to account for reexports. - The backends have to be changed accordingly. Ivan Perez <notifications@github.com> schrieb am Mo., 18. Dez. 2017 um 16:42 Uhr:

…

I'm in a similar position myself: I can try it as it is developed, but this sounds non-trivial for someone who is not familiar at all with the internals of haddock. I cannot commit to completing this at the moment :( How about tagging this with help-wanted? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#123 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiiYUZ9rSrGaohu-MEfH9mVoNapewWks5tBofugaJpZM4B5QoG> .

[treeowl]

I imagine this is to add per-method documentation for each instance? I don't quite understand everything people have said above. If so, @chris-martin is likely interested.

[ivanperez-keera]

@alexbiehl Would it make sense to promote this for hacktoberfest for someone really adventurous, or, if nobody takes it, include it as part of a GSoC proposal if there is any?