Adequate documentation

[kvanbere]

This package is currently only sparsely documented, and none of the module documentation meets the Hackage standards. All files will need a good level of documentation before the initial release, so that new users are not confused.

[Exegetech]

@donkeybonks Looks like a nice project!

I read about this project from the Reddit thread. I'm a beginner Haskell developer, not really proficient with Haskell yet but I know how to work in it decently. I think adding docs will be a great first start. Can you point out where to start?

[kvanbere]

Hi @ChristianSakai !

We’re so glad that you’re interested in contributing!

Some time in the next 12 hours I’ll write up something more detailed about what can be done here. In the mean time it would be helpful to become familiar with the Haddock syntax, particularly export list syntax (headings, etc) and module header syntax (currently we’re lacking entire module headers).

Much of the documentation would be just adding the correct headers and at least a 1 line note on each data type/function so that the reported documentation coverage reaches 100%.

[Exegetech]

EDIT: Thanks @donkeybonks. I'll read up on Haddock syntax. I was looking at the files in src/Github/Data/Webhooks, I assume those are the files that need documentations? How do I check whether a documentation coverage reaches 100%

[kvanbere]

Hi @ChristianSakai

You can generate the documentation by running

$ stack haddock

This might take a while initially and will print the directory with the generated documentation.

Here are some specific things:

• The modules in src/GitHub/Data/Webhooks are missing module descriptions ( https://www.haskell.org/haddock/doc/html/ch03s03.html ).
• After module descriptions are added, some additional documentation may be needed to be added to each function using the -- | Function docs here syntax to reach 100% coverage. You can see that there is some existing documentation already in this style. See also ( https://www.haskell.org/haddock/doc/html/markup.html#idm140354810917952 ).
• Finally, it might make sense to reorganize some modules export list to create a more logical flow of the documentation. This also affects how the documentation table of contents for each module is rendered. See here ( https://www.haskell.org/haddock/doc/html/ch03s04.html ).
• Is there anywhere where it might be beneficial to provide inline examples in the documentation?

You can find information such as copyright and licensing in package.yaml. You can omit the Stability and Portability fields since we consider those useless without a specification defining exactly what they should be.

If there are any other questions just write them here. When you open a PR feel free to also add your name under AUTHORS.

[Exegetech]

Thanks for the response @donkeybonks , I'm currently still trying to read the code base and try to understand how it works. Couple of questions:

1. What does comment Types lifted from the @github@ package. mean?
2. Some functions and type looks straightforward, do we need documentation for that as well? For example, URL and getURL. I think I read about this mindset particularly with Haskell community where documentation is sparse and that is because people can just figure it from the types, curious to hear your explanation here. I agree though that Haskell libraries need to be better in their docs.

[kvanbere]

Hi @ChristianSakai,

1. Those types were copied and pasted from the github package. They are equivalent but to avoid creating a dependency we do not import them in 1.0.0, for now.

2. Yes, we will need documentation for these, even if just a short half-sentence. Because URL is defined as a newtype URL = ... rather than a record constructor, it is a little un-idiomatic. It was done like this so that, by means of newtype, a URL is actually treated as exactly like a Text by the compiler, including in all of the performance rewrite rules.

[Exegetech]

@donkeybonks I tried to build the package and tested the minimal working example works well.

When I run stack haddock it keeps rebuilding the documentation every time that takes time, is there a faster way to do this?

[kvanbere]

@ChristianSakai unfortunately I do not think there is a faster way to build the documentation at this time as it must derive the automatically generated type classes and their code in order to build the documentation.

You should also try these examples ( https://github.com/onrock-eng/github-webhooks/tree/master/examples ) .. they are quite fun.

[kvanbere]

It actually generates quite a lot of documentation too, ie
https://hackage.haskell.org/package/github-webhooks-0.9.1/docs/GitHub-Data-Webhooks-Events.html

For example expand "type Rep CreateEvent" using the little '+' and see how it has automatically derived the type class to inherit and it is very complex and lengthy

[Exegetech]

Ah, yeah that's true. The generated docs are a lot. Very complex stuff, lol.