New Issue: IO module suggested documentation improvements (plus some other questions)

Notifications Issues
1

18522, "lydia-duncan", "IO module suggested documentation improvements (plus some other questions)", "2021-10-05T21:37:42Z"

This issue is a grab-bag of all the things I noticed while going through the documentation in prep for the IO module stabilization effort.

FormattedIO specific changes:

  • [ ] 2nd paragraph of "Overview of Format String" should link rather than merely name the section
  • [ ] C->Chapel table should include examples for clarity
  • [ ] Paragraph after the C->Chapel table is unclear. Are %n and %t Chapel format strings or C ones? (as an example of what is unclear)
  • [ ] In the "Generic Numeric Conversions" section, the paragraph after %{##.###} and %{##} almost implies that both would be padded to 5 digits, despite specifying a different amount of padding. Might be good to rephrase (or adjust %{##} to also specify 5)
  • [ ] Should specify that including "i" for imaginary numbers impacts the width of the output rather than the number of digits printed in the "Generic Numeric Conversions" section
  • [ ] Description of %dz and %ez should repeat what d and e mean, or at least link back to %dr and %er
  • [ ] The "Complex and Imaginary Conversions" section could do more to make it clear that the specifiers that apply to complex numbers can also apply to imaginary numbers
  • [ ] %cS needs clarification of what it means
  • [ ] I think the detailed description should occur before the examples, the current ordering makes it difficult to determine what combinations exist
  • [ ] "# Specifiers" section jumps right in, it should start with a description of what it should be used for.
  • [ ] There are two "Conversion Type" sections under the "% Specifiers" section and they contain different but slightly overlapping information. There should be just one.
  • [ ] The "Formatted I/O Examples" code snippets should imo be interspersed in the rest of the documentation.

Other IO documentation issues:

  • [ ] channel.writef(fmtStr: ?t) is included but without documentation, while channel.readf(fmtStr: ?t) is explicitly "no doc"ed. I think both should be "no doc"ed.
  • [ ] channel.skipField documentation says ENOTSUP is returned, but it is thrown now. The example could also be clarified

Other questions that don't have issues yet:

  • [ ] should getting binary/octal/hex output prefixed with 0b/0o/0x be the default behavior? Or is it appropriate that it has to be explicitly opted into with an additional character?
  • [ ] Would it make sense to use %?i instead of %*i for "read the minimum width from a preceding argument", since Chapel already uses ? for additional specification?
  • [ ] Should string.format and bytes.format stop being tertiary methods? (I could have sworn there was an issue about this somewhere, but I guess not)
  • [ ] Is the reliance on the Regex module okay for format strings with that involve regular expressions? Should these still be supported? If so, should the use of the Regex module be public?
  • [ ] Should the regex-related methods be organized either alphabetically or in order of use case?