Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs for primitive type helper modules should stay in their lane #92777

Closed
camsteffen opened this issue Jan 11, 2022 · 1 comment · Fixed by #93162
Closed

Docs for primitive type helper modules should stay in their lane #92777

camsteffen opened this issue Jan 11, 2022 · 1 comment · Fixed by #93162
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools

Comments

@camsteffen
Copy link
Contributor

Summary of primitive types with corresponding std modules:

Primitive type std module std module docs first line
array std::array Helper functions and types for fixed-length arrays.
char std::char A character type.
slice std::slice A dynamically-sized view into a contiguous sequence, [T].
str std::str Unicode string slices.
pointer std::ptr Manually manage memory through raw pointers.
f32 std::f32 Constants specific to the f32 single-precision floating point type.
f64 std::f64 Constants specific to the f64 double-precision floating point type.

Some of the std modules' documentation sound like documentation for the primitive type itself. Others do not. The std::slice and slice docs almost look like they are supposed to be identical but there are some minor (perhaps accidental) differences. std::ptr has some unique content that may be better fit for the pointer docs.

In general, I think the std docs should be very brief and primarily work as a signpost pointing to the primitive type docs. But of course they should also document the module itself, without sounding like "I am char". Some more specific conventions could be established.

@GuillaumeGomez GuillaumeGomez added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Jan 12, 2022
@slightlyoutofphase
Copy link
Contributor

On a semi-related note, as I mentioned here it's IMO very confusing that on the page for pointer, the Primitive Type pointer methods list in fact includes all of *const T, *mut T, *const [T], and *mut [T], which leads to a large amount of duplicated method names in practice.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants