Allow for C arguments to be labelled as "Parameters" or "Arguments"

[torressa]

Describe the solution you'd like
The easiest solution would be to split arg and argument to a Parameters label with a new TypedField

sphinx/sphinx/domains/c/__init__.py

Lines 297 to 308 in 0504903

	_function_doc_field_types = [
	TypedField('parameter', label=_('Parameters'),
	names=('param', 'parameter', 'arg', 'argument'),
	typerolename='expr', typenames=('type',)),
	GroupedField('retval', label=_('Return values'),
	names=('retvals', 'retval'),
	can_collapse=True),
	Field('returnvalue', label=_('Returns'), has_arg=False,
	names=('returns', 'return')),
	Field('returntype', label=_('Return type'), has_arg=False,
	names=('rtype',)),
	]

Describe alternatives you've considered
Or toggle the label with a flag somehow.

Happy to open a PR if this looks like a viable solution and of course for alternative solutions.

[electric-coder]

Can you remind us of the difference between arguments and parameters and how the current options aren't adequate for C?

[torressa]

It's just the label shown in the documentation. There's a distinction between arguments and parameters in C and some developers prefer the former label when writing their documentation. Currently, only the "Parameters" label can be used.

[electric-coder]

@torressa I don't have Brian Kernighan and Dennis Ritchie's The C Programming Language on hand, but for a definition we can mention Stack Overflow's canonical: What's the difference between an argument and a parameter?

It's just the label shown in the documentation.

Would it be a viable alternative to use .. c:alias:: name? A similar request was made for Python #7609

[torressa]

Would it be a viable alternative to use .. c:alias:: name? A similar request was made for Python #7609

I'm not sure, I tried replacing a function :arg arguments with an alternative declaration. It's a bit messy and doesn't look the same when rendered:

.. c:function:: int foo(Bar *bar)

   This is my foo function description

Need a new line

   Arguments

   .. c:var:: Bar *bar

      This is what bar is

Maybe there's a better way but this renders very different to the standard and more concise:

.. c:function:: int foo(Bar *bar)

   This is my foo function description

   :arg bar: This is what bar is

Could we not add an option for a function that allows for this switch (similar to :single-line-parameter-list:)? This way we don't have to change the source for this small change

[torressa]

We found a solution by overriding the CDomain and replacing the function directive. I think this is still nice to have