doc: Reformat the oneshot speedup-groups information without the table layout #2248
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Description
IMHO the table layout used for the list of methods sped up by
oneshot()
was not really working. Horizontal alignment of various methods meant nothing, so having the platforms side-by-side also meant nothing. Blank rows were hard to spot, making the groupings unclear. Basically, it was just a list of groups-of-methods, formatted so it's difficult to read on narrow screens.This PR folds up each column of the table into a sub-sub-section of a subsection (titled "Method grouping & speedup potential") within the method documentation for
oneshot()
. Each platform section contains an autonumbered ordered list containing from one to three entries, each of which is a comma-separated list of method names.Using this format also allowed me to notice that the Solaris and AIX columns were identical, and combine them into a
Solaris & AIX
section rather than repeating info.I'm open to changing any or all of this as requested, and of course you're welcome to reject it outright if you feel it's the wrong approach.
Example
In the source, the entries are listed vertically, each on a separate line, which makes editing vastly easier. For example:
Rendered, that becomes:
(Or it may wrap, depending on the viewport width.)
Other changes
Other adjustments I made in the course of doing this:
Fixed the alphabetization in BSD (
name
was beforememory_info
), something that would've been tedious to do in the table format, but with this formatting was a simple matter of moving one source line down by two lines.Updated the
.. versionadded
for the method from5.0.0
to4.5.0
, matching other mentions elsewhere in the file.Moved the
.. versionadded
above the new subsection, which seemed to be clearer / make more sense, as having it at the very bottom gave the impression that only the last platform was added in 4.5.0.