Explicit parameter list in function documentation

Wow, that’s a great improvement. Real world examples really helps visualising potential improvement.

6 Likes

I agree wholeheartedly! We have type annotations for years already. Other ways of conveying types could be very confusing.

Could we consider to show the types without round brackets so the displayed form is more aligned with the real syntax?

These I would still show inside the round brackets (or marked some other way) to communicate that it is not a precise type. This way some complex types could be shown by an approximate type annotation without causing a confusion.

2 Likes

I have reservations, in the case of more complex types. Type annotations can be very verbose and unreadable when describing something like “optional async generator taking an int and returning strings”.

Readability should always be the priority here, and type annotations, while readable for simple cases, can hinder that in complex ones.

2 Likes

I don’t think anyone intends to create a super rigid format here; a pragmatic approach is almost always useful. Quoting Steve, earlier in this thread:

If type annotations in the docs can make things clear and easily understood, apply them. If they end up being too verbose, thus creating (more) confusion, don’t apply them. Readability counts.

We all strive towards the same goal: improving the docs.

6 Likes

Since I got quoted… yes, reusing the type annotation syntax where it makes things clearer is fine by me. We can argue about whether one is “too complex” on a case-by-case basis.

Worth keeping in mind that most of our standard library was built around the idea of functions “doing what I mean” rather than being designed for concrete types (as it may have been designed in another language). So we widely use anti-typing-patterns throughout the stdlib, and won’t be redesigning them to become type-first APIs. I expect a significant amount of cases where the “correct” annotation is too complex to be readable or helpful, so planning and explicitly allowing a fallback (since some authors will appreciate the explicit allowance) now will make things smoother.

This approach (parentheses for “not a machine-readable type annotation”) seems perfectly fine to me. Bonus points if we can also (easily) show it in a different font.

2 Likes

Indeed, as I’ve emphasized throughout. The main balance here is between making the guidance simple, unambiguous and consistent to apply, such that we don’t have to analyze and debate every individual case :smiley: and the end product is coherent and useful to readers, while allowing ample flexibility for the classes of cases where it doesn’t make sense and those that are otherwise special/exceptional in some way.

I also am not advocating these become hard requirements or anything for merging docs PRs, as opposed to a basis for guidance, suggestions and improvements.

I figure most have read this, but just to include the full quote to make clear that we’re all on the same page here (emphasis added, with a slight wording tweak to simplify):

4 Likes