Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improve the IO module documentation (chapel-lang#24606)
[reviewed by @jeremiah-corrado] Takes a full pass over the IO module and FormattedIO module documentation with an eye for inconsistencies, outdated information, readability, and allowing users to quickly navigate to related features. <details> - Remove some mentions of offsets in the intro section - add `use IO` to the examples so they compile independently - replace "file offset 0" with "the beginning of the file" in the examples - add "locking=false" to the examples so they compile without a deprecation warning, and explain why it is used in the comment - Use a "/" to separate `fileReader` and `fileWriter` when introducing `openReader`/`openWriter` so it is clear that they are grouped together rather than having it potentially be ambiguous with "open a file and create a fileReader" or "create a fileWriter". - remove a mention of "underscore" methods, those are gone now - remove a mention of the fileReader/fileWriter style, that is also gone - replace a "start" mention with "region", which is the new argument name - replace mentions of "readThis"/"writeThis" with "deserialize"/"serialize" when the later part of the sentence already linked to the latter. - Don't talk about stdin/stdout/stderr's "kind" setting, that isn't specified any more - Point to the beginning of "Handling Errors" instead of "Complete Handling", the former is more generally applicable. - insert spaces in a bulleted list to stop one of its bullets from becoming bold - de-capitalize "fileReader" and "fileWriter" to match the types' names - Remove outdated mention of the default locking behavior for fileReader/fileWriter - fix some line overlap - Fix the deprecation message for `ioendian` to use tags properly and link (and updated the tests of that message) - Don't say "a file.reader", say "file.reader" - add some missing words - Make many places in the serializer/deserializer docs link to the types and functions they are referring to - fix some broken links - Make use of Jade's fix for nested record links - Turn a section title mention into an explicit link to that section - Remove the binary conversions warning, since the work there is old and done - Be slightly more explicit about the `%n` specifier being from Chapel - Adjust the `%{##}` example so it is consistent with the following paragraph - Fix a typo using `${#####}` instead of `%{#####}` - Fix a missing column specifier - Repeat what `%d` and `%e` mean when used with complexes, since we can't link back to the original definition - Unify the two `[conversion type]` sections and remove the second one - Correct an internal comment about where the documentation for a function is located - remove the warning about the IO documentation having inconsistencies and being under development </details> Verified the changes with `make docs` and passed a full paratest with futures (checked due to the impact on the deprecation message of one symbol)
- Loading branch information