20706, "jeremiah-corrado", "Should we improve the integration of the 'String' and 'Bytes' Lang-Spec pages", "2022-09-23T14:40:30Z"
Following Migrating `string` docs from "Build-in Types and Functions" section to "Language Specification" by jeremiah-corrado · Pull Request #20625 · chapel-lang/chapel · GitHub and Migrating `bytes` docs from "Build-in Types and Functions" section to "Language Specification" by jeremiah-corrado · Pull Request #20622 · chapel-lang/chapel · GitHub, some questions arose about how well the new strings and bytes documentation pages are integrated into the remainder of the language-spec. I.e. if you were to read the spec end-to-end, do they feel like they belong, or were just dropped-in? (For context, these used to be "Built-In Types and Functions" pages, but were migrated as a part of: Move the Built-in Types and Functions docs into the spec · Issue #18027 · chapel-lang/chapel · GitHub)
For example, the Types Page lists them as "primitive types"; however, the full pages sit under the "Composite Types" heading here. So, do they belong in both places?
One option to improve the current status, is to create a separate heading on the Langauge-Spec page called "Primitive Types" (or something similar), which would house the Strings and Bytes pages. Under this same heading, we could also create a "scalar types" or "math types" page containing the relevant/analogous information for: bool, int, uint, real, imag, complex. The logic being that String and Bytes are rich enough types to warrant their own pages, but each of the scalar types probably aren't, and thus could share a language spec page. (The scope of the Types Page would be reduced under such a proposal).
Various other small changes could be implemented to help the docs feel more coherent w.r.t string and bytes. For instance, the String type is referenced in various places throughout the docs, but few of these references actually link to the new String page. (ex: Expressions — Chapel Documentation 1.28)