Add kdoc for MonadThrow

[JorgeCastilloPrz]

fixes #1111

Would we need to add a specific section for MonadThrow in the Type Classes docs section, apart from the already generated dokka one in API Docs / Typeclasses ? In case we do, what should it describe?

• Add dokka docs to MonadThrow
• Double check how they look

[raulraja]

Can we add a playground example similar to those in Bracket and Functor that illustrates the usage of bindingCatch ?

[raulraja]

Monadthrow it's just a MonadError<F, E> where E is Throwable. A brief sentence with a link to MonadError should be enough IMO for now. What it has now it's good for the time being. We have many more type classes to document and this one it's just a specialization and it was created so bindingCatch would only be exported as extension over data types whose error type is Throwable.

[JorgeCastilloPrz]

Since I had it done since yesterday I've pushed the playground. It looks like this now:

Let me know if you wanna keep all this or not 👍

[JorgeCastilloPrz]

Can we merge this @raulraja or should we revert to that one liner you mention ?

[raulraja]

The example is good but it needs to use the extension_factory bindings so when it's projected to each extension it uses the extension factory instead of the hardcoded IO.async()

[JorgeCastilloPrz]

Can you share an example of that?

[nomisRev]

@JorgeCastilloPr you can find examples in Async and Functor.

[JorgeCastilloPrz]

Thanks I'll fix it tomorrow.

[JorgeCastilloPrz]

I've updated the sample to use _extensionFactory_ but doesn't look very good. Something got broken. I assume I'm doing something wrong but to be completely honest I'm a bit clueless without docs about how to do this. Could you double check my last commit and tell me what's happening @raulraja? That would be helpful.

After comiting that, the snippet disappeared from docs and looks like this:

Is it about labeling it as extension?

[raulraja]

The extension example can be added in the same way as in Functor. the example goes in the header of the class and when it is postfixed by :extension is removed from the type class docs and projected only in the extensions. Try to make it resemble the same format as in functor which we know that it works: https://github.com/arrow-kt/arrow/blob/72b4c13b6fa3bf4b20eb4e51e47d067649dda23c/modules/core/arrow-typeclasses/src/main/kotlin/arrow/typeclasses/Functor.kt

[raulraja]

it may be that it worked but you have to look in the extensions when looking at the docs. For example the Try MonadThrow extensions. Let's see if it projected the example there and you can make it run

[JorgeCastilloPrz]

I don't really know what I'm doing wrong, but can't really make this work. Adding what's on this commit I'd expect to get a simple runnable snippet showcasing instatiation projected to extensions (like the one for functor), but I can't either see any sample projected in the Try.monadThrow docs for example.

Given that there are no docs on how to use Ank for this and that it takes a very big while to trial and error, I'd need some help with an actual commit fixing what's bad here to understand how it should be done. That's gonna be faster most likely.

[nomisRev]

@JorgeCastilloPrz

I fixed the docs, and to summarize the steps you have take.

1. Add @documented to the typeclass you want to document

2. Annotate the snippet with kotlin:ank:playground:extension if you want the snippets to be inlined on the corresponding extensions. i.e. arrow.core.extensions.try.monadThrow.monadThrow or arrow.core.extensions.try.monadThrow.bindingCatch

3. Annotate the extensions you want to be skipped with @undocumented currently this is useful for typeclasses with dependencies on other typeclasses which might not be solveable atm by the Ank compiler.

4. Write your snippets using _methodName_ for extension methods which should be replaced by the Ank compiler, and _extensionFactory to obtain the typeclass instance.

5. run ./gradlew clean dokka :arrow-docs:runAnk to compile the documentation

6. Check if the documentation was correctly inlined for the given extension i.e. for MonadThrow check /arrow/modules/docs/arrow-docs/build/site/docs/apidocs/arrow-core-extensions/arrow.core.extensions.try.monad-throw/binding-catch.md

Can you double check if I missed something @raulraja?

@JorgeCastilloPrz care to update the documentation docs with this information?

[JorgeCastilloPrz]

Ok thank you so much for your help @nomisRev. I wish I would have known anything about the @Documented annotation before 😅. I've added those ideas to #1236 so we can update Ank docs with all that info.

This works for me. If it's okay for @raulraja we can merge.

[raulraja]

We should add a link in the type classes section that points to the main page in the apidocs for MonadThrow. fine in a different PR. Great stuff @JorgeCastilloPrz 👏