args: omit all lamda args. To force explizit documentation of them.

[hsjobeki]

This fixes a problem, that arose during the migration to doc-comments.

@DanielSidhion and me already started migrating to doc-comments (lib.asserts is already migrated), and encountering having arguments double documented. Just deleting the adjacent comments can't fix this.

With this PR we can assume arguments are documented explicitly in the lambda documentation as:

{

/** 
# Inputs

foo

: some foo docs

*/
f = foo: 1;

}

The issue is, that we automatically create empty default documentation for non documented arguments. (which is fine for the legacy path)

I've found it fine to assume that having a doc-comment is enough to assume that there is no need to magically add argument documentation for now, since the doc-comment should already includes those.

At a later point in time, we may add argument documentation for doc-comments as well. Because we specified them for lambda formals (structured arguments) I am still working on the roadmap how to integrate them.

[hsjobeki]

@infinisil Some context

[DanielSidhion]

To give some more context for the future:

We plan on eventually supporting docstrings on the function AND docstrings on the function arguments at the same time. Doing that requires us to understand the layout of function arguments on the overall function documentation.

If we wanted to, we could've read the current documentation for all functions in lib and figured out a layout that would work for every case. However, the current documentation is very poor, so whatever decision we make right now might not be a good one for the near future.

Instead, we decided to:

• Adopt the most flexible documentation approach (ignore argument docstrings, trust that the function docstring talks about the arguments in whatever format it wants)
• Wait until efforts to go through the Nixpkgs manual to update documentation makes a pass at the lib functions.
• At that point, look at all the ways that function arguments are documented and figure out a layout that would work well for all cases, and then work backwards to define how to combine function docstrings + function argument docstrings

[infinisil]

Looking good to me!

That also sounds like a great plan :D