Make kernel parameter documentation in kernel and PyNEST consistent

[JanVogelsang]

Fixes #1554

Added all missing parameters in the kernel_manager's docstring, made the whole docstring consistent and fixed the parameter order (alphabetical order within groups).

[jessica-mitchell]

Thanks @JanVogelsang for the update. I think there is one parameter missing and that's kernel_status. Could you please add it?

[jessica-mitchell]

lgtm!

[heplesser]

@JanVogelsang Thank you for working through this! I added a number of suggestions on details.

I then have a general question @jessica-mitchell: Within each group of parameters, parameters are currently ordered alphabetically. This leads to quite some bit of mixing, e.g., of min_, max_ parameters. I wonder if it would not make more sense to order parameters logically also within groups. I also wonder if we should not make more of an effort to move doc on parameters that users will inspect or change frequently forward and those only interesting for power users/developers towards the end.

[JanVogelsang]

It might make sense to have a different grouping (or any groups at all) in the PyNest API documentation compared to the docstring in the source code (which probably only developers will ever get to see).

Should I also apply all your changes to the PyNest documentation as well (which is based on a different file)?

[jessica-mitchell]

I then have a general question @jessica-mitchell: Within each group of parameters, parameters are currently ordered alphabetically. This leads to quite some bit of mixing, e.g., of min_, max_ parameters. I wonder if it would not make more sense to order parameters logically also within groups. I also wonder if we should not make more of an effort to move doc on parameters that users will inspect or change frequently forward and those only interesting for power users/developers towards the end.

@heplesser We could certainly look at moving these around; I am not familiar enough with some of the functions to know which ones would be considered more developer-leaning. Would the entire nestModule class be considered something to be moved lower (or another page?). Or is it more fine-grained than that?

[heplesser]

We should discuss this in the next NEST Developer VC. It is unfortunate to have the same information twice in ever so slightly different format. I hope we can find a way to have it only once and then just extract it in sensible ways.

[heplesser]

@JanVogelsang In the meantime, would you accept my suggestions (if you agree with them) and run clang-format on the file to get the formatting right?

[JanVogelsang]

@heplesser I reviewed all your requests and accepted most of them. I changed some of them to keep up a consistent formatting by replacing commas by semicolons inside parentheses, when they are not used within a sentence/block. If you prefer commas everywhere instead, I can also replace all semicolons by commas, I just want to make sure I use either of both consistently.

[heplesser]

Thanks @JanVogelsang! In spite of my comments above, I suggest to merge this PR now once all tests pass, since it provides an improvement. We can then handle the ordering of parameters and possible integration between kernel and PyNEST in a separate PR.