As discussed in a comment, we should reorganize docstring content such that parameters and return values are documented immediately after the interface definition and initial description and such that explanatory notes, including special cases, are documented in a separate section immediately following documentation of return values and/or raised exceptions.
This reorganization will ensure that parameters and return values are more prominently displayed and are closer in proximity to the API definition. Currently, for those APIs with many floating-point special cases, a definition and its associated parameter descriptions can be spaced far apart, thus requiring a user to scroll to view desired content and preventing the user from viewing the definition and associated descriptions within the same view at the same time.
As discussed in a comment, we should reorganize docstring content such that parameters and return values are documented immediately after the interface definition and initial description and such that explanatory notes, including special cases, are documented in a separate section immediately following documentation of return values and/or raised exceptions.
This reorganization will ensure that parameters and return values are more prominently displayed and are closer in proximity to the API definition. Currently, for those APIs with many floating-point special cases, a definition and its associated parameter descriptions can be spaced far apart, thus requiring a user to scroll to view desired content and preventing the user from viewing the definition and associated descriptions within the same view at the same time.