You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As discussed at length on the recent Discourse thread, logging.Formatter is a great example of a function that would particularly benefit from an explicit list of parameter names, defaults and types, like most if not nearly all third-party Python library API docs use. This will help the reader quickly, easily and accurate find the specific information they are looking for (and ensure it is present in the first place), per the primary goal of reference documentation.
The proposed revision was well-received there, so I'm going ahead with a PR here. This, in combination will followup PRs, will also reduce the substantial inconsistency between how nearby functions/methods of comparable complexity are presented, and help serve as an additional empirical testing of the proposed explicit, structured approach to be incrementally adopted on a wider scale, particularly for more complex functions like this one. Also, it revises the text to reduce or eliminate duplication and redundancy while retaining all the same information, making it much more concise and easier to read, and phrase it more clearly and directly.
Preview before and after:
The text was updated successfully, but these errors were encountered:
As discussed at length on the recent Discourse thread,
logging.Formatter
is a great example of a function that would particularly benefit from an explicit list of parameter names, defaults and types, like most if not nearly all third-party Python library API docs use. This will help the reader quickly, easily and accurate find the specific information they are looking for (and ensure it is present in the first place), per the primary goal of reference documentation.The proposed revision was well-received there, so I'm going ahead with a PR here. This, in combination will followup PRs, will also reduce the substantial inconsistency between how nearby functions/methods of comparable complexity are presented, and help serve as an additional empirical testing of the proposed explicit, structured approach to be incrementally adopted on a wider scale, particularly for more complex functions like this one. Also, it revises the text to reduce or eliminate duplication and redundancy while retaining all the same information, making it much more concise and easier to read, and phrase it more clearly and directly.
Preview before and after:
The text was updated successfully, but these errors were encountered: