Skip to content

Commit

Permalink
Improve the IO module documentation (chapel-lang#24606)
Browse files Browse the repository at this point in the history
[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
lydia-duncan authored Mar 14, 2024
2 parents 1a3f8b1 + 8c7d735 commit 3c96029
Show file tree
Hide file tree
Showing 3 changed files with 333 additions and 320 deletions.
Loading

0 comments on commit 3c96029

Please sign in to comment.