Break long function declarations into one parameter per line

[shimizukawa]

C function declarations that have many (or long) parameters resulting in a line break are hard to read. Would it be possible to optionally break them with one parameter per line (like doxygen).

I.e. instead of

size_t process_function(const void *source, void *destination, size_t length, void *data, int (*callback)(size_t, size_t, size_t, void *),
void *cbparam)

I would like something like

size_t process_function(const void *source,
                        void *destination,
                        size_t length,
                        void *data,
                        int (*callback)(size_t, size_t, size_t, void *),
                        void *cbparam)

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1514
• Originally reported by: Jørgen Ibsen
• Originally created at: 2014-07-20T21:54:00.516

[JavierJF]

I would like to participate in the implementation of this feature @shimizukawa. Do you have any plans or known starting point for it?

[tk0miya]

This is not an issue that he posted. This was migrated from bitbucket. The original author is Jørgen Ibsen.

Originally reported by: Jørgen Ibsen

BTW, this is related with writer modules. So I guess sphinx/writers/html.py (html5.py) is related with this.

[JavierJF]

@tk0miya yes, I knew it was a imported issue, but I saw that was labeled by him several times. Thanks for the info about the related module, I have looked into it and I think it's possible to sketch something. But probably the best will be trying to expose a setting for configuring it, like a number of parameters in which start doing the line-breaking.

[jakobandersen]

It should be doable only by modifying individual domains. A domain is given a node to render a signature into. That node is a addnodes.desc_signature. Instead of directly adding child nodes to it, you can set is_multiline = True, and only add addnodes.desc_signature_line nodes as children. In those you can then add fragments of a signature. The C++ domain does this for templates.

[JavierJF]

@jakobandersen Nice info thanks, I'm going to start with that. Reading first how that was integrated in the C++ domain.

[hzhwcmhf]

I‘m facing the same issue in python. Is there any update?

[jakobandersen]

The missing(?) part in implementing this is how to do indentation. E.g., for a function def f(a, b, c, d), which should be broken into, say, def f(a, b and c, d) we need some way to precisely indent the second line, taking whatever formatting of the signature happens into account. Is there such a thing in docutils? In Latex we could render a fake prefix into a \phantom. E.g, (with an ad hoc made up markup):

\kw{def} \textbf{f}(a, b\\
\phantom{\kw{def} \textbf{f}(}c, d)

This would make whitespace taking up the exact space needed. However, is something similar to this possible in HTML+CSS without too nasty haxes? and how with other output formats?