Should all the documentation be in docstrings?

[Uran198]

Branched from #1967

Is it a good idea to have such a large docstrings? Mostly, names are self descriptive and this huge kind of stuff can be added to documentations or references. Then, for some bears we can use **kwargs and just pass parameters as they are. Possibly, documenting each of them.

@sils1297 comment:

I personally really like that you can write all the documentation for the bear in the code and you don't have to think about where to write docs. And coala (i.e. we) takes care of organizing it properly for the user.

[gitmate-bot]

Thanks for reporting this issue!

Your aid is required, fellow coalaian. Help us triage and solving this issue!

CC @sils1297, @AbdealiJK

[Makman2]

I'm in for this, see my comment in #1967.

[Makman2]

I think API-documentation belongs to the code, then you have directly the code beneath. Even if some names are self-descriptive, often types/parameter inputs must be specified, and Error behavior needs also specification. I want them too like we have now^^

[Uran198]

My concern is that it is not very convenient to have functions with more than 20 parameters and if you're even familiar with the program that bear uses to do it calculations you will still have to go either the code or huge signature to figure out if everything is the same and what not. They may even have these tools configured, but they will not be able to switch easily.
I also I like error behaviour specified and this can be done right in the description.

[Makman2]

But if you are not familiar with the code, it's way easier to read a docstring instead of code (especially if you are new to python).
Function with more than 10 parameters are quite rare in our codebase, they would only likely appear in bear signatures, and that's way easier to have in docstrings than in external files.

[Adrianzatreanu]

This issue was moved to coala/documentation#47