Skip to content

Deal with libcore/libstd doc duplication on primitives #30214

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.

Sign up for GitHub

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

Jump to bottom
Closed
alexcrichton opened this issue Dec 4, 2015 · 5 comments
Closed

Deal with libcore/libstd doc duplication on primitives #30214

alexcrichton opened this issue Dec 4, 2015 · 5 comments
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. P-medium Medium priority T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Comments

@alexcrichton
Copy link
Member

Right now there are a number of extension traits in libcore that are being stabilized, including:

  • SliceExt
  • StrExt
  • CharExt
  • Float

These all currently have very little or no documentation because all the actual docs live elsewhere (e.g. libcollections, libstd, librustc_unicode, etc). When browsing the libcore-only docs, however, this may be a bit jarring, so we may want to resolve this somehow. A few strategies possible are:

  1. Duplicate all the docs. Pros are that it's all there where you need it, cons are that the two will inevitably get out of sync and duplication is always bad.
  2. Add links from core docs to std docs. Pros are that it's easy to maintain and add new APIs without excessive duplication, cons are that you've gotta click to see the docs.
  3. Automatically merge std docs into core. Pros are that it's easy to maintain and you've got everything where you need it, cons are that it's difficult to implement.

I'd vote for route (2) personally.
@alexcrichton alexcrichton mentioned this issue Dec 4, 2015
Merged
@aturon
Copy link
Member

aturon commented Dec 4, 2015

(2) seems like the most pragmatic for the time being.

@sfackler
Copy link
Member

sfackler commented Dec 4, 2015

I'd go for 2 as well.

@steveklabnik
Copy link
Member

3 is really tough, but is gonna bit us with core docs anyway, for like... everything.

2 seems best here for now.

@steveklabnik
Copy link
Member

Hm, so I can't actually find the doc pages for these traits.

@ghost ghost mentioned this issue Feb 29, 2016
Merged
@steveklabnik steveklabnik mentioned this issue Feb 29, 2016
Closed
steveklabnik added a commit to steveklabnik/rust that referenced this issue Mar 1, 2016
@steveklabnik
Rollup merge of rust-lang#31965 - miqid:doc, r=steveklabnik
5b91fc0 
Hello.

Quite a few of the links in the `core` module concerning redirection to additional primitive type documentation are broken. I noticed in rust-lang#30214 that there seemed to be a consensus with linking across to `std` module documentation from the `core` module. This is what I've done with the `core` modules for primitive types.

If the changes here are good to go forward with, I'll happily tend to adding more documentation links for the extension traits in the aforementioned issue if need be.

r? @steveklabnik
@steveklabnik steveklabnik added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Mar 10, 2017
@steveklabnik steveklabnik added P-medium Medium priority T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. and removed A-docs labels Mar 22, 2017
@Mark-Simulacrum Mark-Simulacrum added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Jul 24, 2017
@steveklabnik
Copy link
Member

Update: these traits have been removed, and replaced by inherent impls. As such, this ticket is moot. Closing!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. P-medium Medium priority T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@steveklabnik @alexcrichton @aturon @sfackler @Mark-Simulacrum