Completely revised iaf_psc_alpha user documentation

[heplesser]

This PR provides completely new version of the user documentation of iaf_psc_alpha with a focus on the equations underlying the model. I provide this as a suggestion for how to re-write model documentation. It can probably do with a bit of polishing before being used as template for other models.

[jessica-mitchell]

Also relates to issue #2464

[heplesser]

@jessica-mitchell @jougs @clinssen @janskaar Thank you for your comments, I have followed up almost all of them. Please have a look.

I am struggling with one problem now: The parameter table in the comment is 129 characters wide, so clang-format complains. Is there any way to either suppress clang-format for this comment or break lines in a RST table spec?

https://github.com/heplesser/nest-simulator/blob/1e203c9e5c9ac914ea59f640b1bc185217c35c5d/models/iaf_psc_alpha.h#L137

[nicolossus]

I am struggling with one problem now: The parameter table in the comment is 129 characters wide, so clang-format complains. Is there any way to either suppress clang-format for this comment or break lines in a RST table spec?

@heplesser I think you can disable and re-enable clang-format like this:

// clang-format off
/*
<docs>
*/
// clang-format on

This will, however, suppress clang-format for the all the documentation. I don't think it is possible to suppress the table only.

[heplesser]

I am struggling with one problem now: The parameter table in the comment is 129 characters wide, so clang-format complains. Is there any way to either suppress clang-format for this comment or break lines in a RST table spec?

@heplesser I think you can disable and re-enable clang-format like this:

// clang-format off
/*
<docs>
*/
// clang-format on

This will, however, suppress clang-format for the all the documentation. I don't think it is possible to suppress the table only.

Thanks, this worked!

[jougs]

While I generally agree with many things said here to improve the model documentation, I also feel we should not overthink (and overdo) this by putting too much effort into adding new things.

In my opinion, this PR should rather serve as a playground and result in a solid template that can be ported to the NESTML documentation generation pipeline. This is where the magic happens now and improvements there would immediately benefit all models (c.f. model equations, units and defaults for parameters, model characterization figures in this example).

In the last three years we only gained 3 new models in NEST (jonke_synapse, cm_default, spike_injector) and I would rather put some increased effort into a better integration of NESTML into the build process of NEST and let all models be generated instead of fixing equations and parameters in manually written model documentation.

@clinssen, @poojanbabu, @jessica-mitchell.

Just my 2 cents.

[heplesser]

@jougs I fully agree with you. I now have one question concerning your earlier comments vs the playground perspective. I entirely agree that it would be useful to link terms in the documentation to glossary entries. But I fear it would be at least another two weeks until I will get around to creating the glossary entries. Would you be ok with merging this now and creating a follow-up issue for glossaryfication?

[heplesser]

@clinssen @jessica-mitchell Could you re-review?

[jessica-mitchell]

thanks lgtm!

[clinssen]

You define I_syn,ex but not I_syn,in. Perhaps you could use the notation I_syn,x or just mention that I_syn,in is defined similarly to I_syn,ex. I am otherwise happy with the changes. Much obliged!

[heplesser]

You define I_syn,ex but not I_syn,in. Perhaps you could use the notation I_syn,x or just mention that I_syn,in is defined similarly to I_syn,ex. I am otherwise happy with the changes. Much obliged!

Thanks for catching this, @clinssen! It should now be fixed.

[heplesser]

@clinssen Ping!