Group all samples after the description of parameters and status code

[olivier-heurtier]

[ikalnytskyi]

Hey @olivier-heurtier! Thanks for the patch. Can you please shed a light on the rationale behind this change? Why do you want to group all examples after descriptions?

[olivier-heurtier]

Hi @ikalnytskyi I tend to think a documentation is more readable when I have the full description first (with all the parameters, the errors, etc.), and then the examples. Putting the examples in the middle of the description makes the different parameters less identifiable. This is of course only my personal opinion. In addition, this makes the output more similar if option :examples: is used or not used

[ikalnytskyi]

@olivier-heurtier I'm a little bit concerned that there are some who will oppose you and say that the examples must be shown where other information about responses is shown. Just to clarify, are you concerned about showing example for a request body? Or for responses? Since responses are shown at the end, I'd assume it's ok to show them there. And as for a request body example, hm, what if we render a request body parameter as the last parameter in the list (i.e. before responses)?

[olivier-heurtier]

@ikalnytskyi what if I add a directive option to activate the grouping of all examples? Any suggestion for the name?

[ikalnytskyi]

@olivier-heurtier can we please put this on hold for a while? It's hard to maintain rendering options in the way it's written right now. I have some thoughts how to improve it, and I plan to try it this week.

[olivier-heurtier]

It's ok for me.