Closed hsjobeki closed 5 months ago
@infinisil Some context
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:
lib
functions.
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:
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.