Automatic documentation for method arguments

Question

Question

Sinon Galvin · Feb 28, 2024

Hi Community,

Can anyone point me to the docs that show how to add automatic class documentation for the arguments used in a method call? I can auto document the class, methods, properties etc. with the "///" but can't figure out how to get the nice argument documentation for the arguments used when calling a method.

Thanks in advance

Discussion (10)4

Log in or sign up to continue

Timo Lindenschmid · Feb 29, 2024

If you mean something like this?

This is essentially only displaying a "good" functional spec definition plus /// supplied documentation.

1 0

score 1 · Answer 1 · 2024-02-28T13:42:50-05:00

I'm not sure what you mean with "the nice argument documentation for the arguments".

Do you have an example?

score 0 · Answer 2 · 2024-02-28T13:59:33-05:00

Hi Enrico, what I thought I had seen somewhere worked like this scenario: you are writing code to call a previously defined method, and as you work through the arguments in your IDE of choice (mine = VSCode) you are presented with help strings for the specific argument you are currently working on for the call, as opposed to a a general help text that explains the method and its input arguments. I went looking for an example and couldn't find one, so perhaps I was imagining it or had my wires crossed for IDEs / Languages 🤷‍♂️

score 1 · Answer 3 · 2024-02-28T13:51:55-05:00

An example would be helpful .... typically I will put argument documentation in my /// comment for the method, and use the <var>arg</var> tags to change the styling of the argument names in the method documentation to make it clear that it's referring to the argument.

score 1 · Answer 4 · 2024-02-28T14:05:07-05:00

Thanks Ben. See my note to Enrico. The missing example may not exist 🤦‍♂️.
Will have to try the var tagging.

score 1 · Answer 5 · 2024-02-28T14:06:25-05:00

Got it - that would be a really great enhancement request though! I would love to see that in action in VSCode :)

score 1 · Answer 6 · 2024-02-29T10:25:49-05:00

That's the framework for sure Timo. Envisioned something that gave more specific hinting as you worked through the argument list. Like a /// for each argument specifically. I am pretty sure that I just imagined it, but like @Ben Spead said, It would be great action in VS Code. May have to go down the VSCode Rabbit Hole now.

score 0 · Answer 7 · 2024-02-29T10:44:50-05:00

Ben Spead · Feb 29, 2024

nice visual :)

0 0

score 1 · Answer 8 · 2024-02-29T12:36:09-05:00

and that screen capture demonstrates why good class documentation especially method descriptions are super valuable including when you are using VS Code.

score 1 · Answer 9 · 2024-02-29T12:40:05-05:00

Absolutely! In fact, I'm planning a project for my team so that our CICD pipeline will throw a failure if someone checks in a method, property, parameter in a class without Documatic (///) content. Of course, just because comments exist doesn't mean it is good, but that's at least a place to start!