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

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.

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

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.

@torressa

@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

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

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

Navigation Menu

Repository navigation

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

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	_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',)),
	]

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

Description

Activity

electric-coder commented on Aug 20, 2024

torressa commented on Aug 21, 2024

electric-coder commented on Aug 21, 2024

torressa commented on Aug 28, 2024

torressa commented on Sep 4, 2024

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions