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

Tracking issue for #[doc(cfg(…))], #[doc(cfg_hide(…))] and doc_auto_cfg #43781

Open
3 of 4 tasks
kennytm opened this issue Aug 10, 2017 · 80 comments
Open
3 of 4 tasks
Labels
B-unstable Implemented in the nightly compiler and unstable. C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. F-doc_auto_cfg `#![feature(doc_auto_cfg)]` F-doc_cfg `#![feature(doc_cfg)]` T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@kennytm
Copy link
Member

kennytm commented Aug 10, 2017

This is a tracking issue for the #[doc(cfg(…))] attribute (feature: doc_cfg) introduced in #43348 and #[doc(cfg_hide(…))] (feature: doc_cfg_hide) attribute introduced in #89596, along with the doc_auto_cfg feature introduced in #90502.

Steps:

(cc #1998)

@Mark-Simulacrum Mark-Simulacrum added C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. labels Aug 10, 2017
@kennytm kennytm added T-dev-tools-rustdoc and removed T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. labels Oct 21, 2017
fengalin added a commit to fengalin/gstreamer-rs that referenced this issue Mar 17, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target plateform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
fengalin added a commit to fengalin/gstreamer-rs that referenced this issue Mar 17, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
fengalin added a commit to fengalin/gstreamer-rs that referenced this issue Mar 18, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
fengalin added a commit to fengalin/gstreamer-rs that referenced this issue Mar 19, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
sdroege pushed a commit to sdroege/gstreamer-rs that referenced this issue Mar 19, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
@QuietMisdreavus QuietMisdreavus added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. and removed T-rustdoc labels May 15, 2018
charlie-ht pushed a commit to charlie-ht/gstreamer-rs that referenced this issue Oct 28, 2018
There are different implementations and signatures for `get_pollfd` depending
on whether the target platform is unix or windows. When generating the doc,
we need both implementations to appear regardless of the target platform. This
commit is inspired by the way Rust `std` library deals with `process::Command`
OS dependent variants
(https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt).

Documentation can't be accurate though as we can't use the`std::os::windows`
on `unix` and vice versa. As a workaround a fake fd class matching the other
platform is declared.

This could be further enhanced once `#[doc(cfg(...))]` is stabilized
(rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]`
or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported
on **Windows/Unix** only`. Unfortunately, these comments disappear when
generating will `--all-features` because they are not part of the documentation
in the gir file.
@sfackler
Copy link
Member

sfackler commented Jan 7, 2019

#[cfg(rustdoc)] is also gated on this issue but seems distinct (and less risky). Could we FCP that portion in particular?

asomers added a commit to asomers/futures-locks that referenced this issue Jan 30, 2019
asomers added a commit to asomers/futures-locks that referenced this issue Jan 30, 2019
asomers added a commit to asomers/futures-locks that referenced this issue Jan 30, 2019
@asomers
Copy link
Contributor

asomers commented Jan 30, 2019

I think that #[cfg(rustdoc)], when applied to structs, should automatically skip any non-public members. That would greatly reduce the amount of extra typing required by crates like Nix.

@Nemo157
Copy link
Member

Nemo157 commented Jul 4, 2019

I was just trying this out for documenting crate features, it "works" but if this is a potential usecase it would be nice to special case the rendering for it:


Screenshot 2019-07-04 at 12 35 06


Screenshot 2019-07-04 at 12 35 27

@Nemo157
Copy link
Member

Nemo157 commented Jul 4, 2019

There is also the issue that it repeats every feature on every item in a page:

Screenshot 2019-07-04 at 14 17 45

When I last attempted to do something about rendering features I found it much more useful to separately keep track of "all required features" to render at the top of the items page and "newly introduced features" to render on the sub-items on the page, so you don't get this distracting repetition on every item.

@dtolnay
Copy link
Member

dtolnay commented Dec 25, 2019

We tried out this feature in Syn (dtolnay/syn#734) and decided against using it yet.


What I am happy with

I like how the message turns out at the top of the doc page of a single type or function.

We had previously displayed this information using an italicized note, which was less noticeable.


What I am not happy with

Our index page becomes extremely noisy. I wish there were a way to not show all of these in our case. It is enough to have this information on the type's individual page. Cfg combinations are not among the most important information to show on the index page.

Also inheriting the same note onto every public field seems unnecessary in our use case.

@jyn514
Copy link
Member

jyn514 commented Dec 16, 2022

As a reminder, this is a tracking issue for stabilizing doc_cfg. Bug reports should go in separate issues to avoid pinging the 30+ people watching this issue, unless you think the bug is so severe it should block stabilization. Suggestions for enhancements should also go in separate issues.


As far as I can tell, the current status is that the stabilization PR (#100883) is blocked on deciding whether doc_auto_cfg should be on by default or not (and whether we should let crate authors control whether it's on or just force it on). The discussion for that is in https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Discussion.20about.20.60doc_cfg*.60.20features.20stabilization/.

@GuillaumeGomez
Copy link
Member

Thanks for the sum up. We actually decided to go through an RFC that started to be written because too many elements need to be discussed. More information in the next weeks.

@joseluis
Copy link
Contributor

Since I see an RFC is being written, I take the opportunity to share my case, since I wanted to use doc_cfg to show that a particular function is only available on the absence of a feature. But it seems that's not currently possible.

This does result in: "Available on feature safe only".

#[cfg(feature = "safe")]
#[doc(cfg(feature = "safe"))]
pub fn safe_fn() {}

But this results in: "Available on non-crate feature safe only". Instead of the expected: "Not available on feature safe".

#[cfg(not(feature = "safe"))]
#[doc(cfg(not(feature = "safe")))]
pub fn unsafe_fn() {}

I wonder if this is by design.

@Nemo157
Copy link
Member

Nemo157 commented Feb 19, 2023

I wonder if this is by design.

Somewhat, yes. Cargo itself doesn't support negative features, so no effort was put into making them render well.

@nic-hartley
Copy link

Should the original post link to #100883 instead?

@seancroach
Copy link

I'm running into a rather annoying problem with documenting features.

I am writing currently a serde crate with multiple specifications for a specific format. I have a binary module that is documented with the following doc_cfg: any(feature = "be", feature = "le", feature = "varint"). Now, if I document one of the functions as present with just the be feature and inline their re-export I get this annoying display:

image

Of course, I tried with doc_cfg_hide, wrestling with the minimal documentation, but nothing seems to work for this. I can not inline the re-exports, but purposefully sacrificing usability is presumably a bug or at least something worth mentioning here. When I don't inline it, it looks like so:

image

My one gripe with the first selection is that even the order it's appended to is non-uniform, which bothers me, but that's not the core issue here.

Is there some hack I'm unaware of besides not inlining items in documentation? I haven't seen this case discussed so far. Even if I simplified it to an internal feature (binary) it still displays, even if assumed to be enabled in context; either way, extraneous information is applied, and I have no say in omitting it.

@GuillaumeGomez
Copy link
Member

#[doc(no_inline)]

@seancroach
Copy link

seancroach commented Apr 16, 2023

I believe #[doc(no_inline)] (as described here) is specifically the behavior I'm trying to avoid. As you can see, binary is a public module.

image

I understand this is stylistic, but every serde_* crate uses #[doc(inline)] on their re-exported functions. This is the behavior I want.

The behavior I don't want is my inability to omit the automatically appended features. It introduces a ton of noise. Even if I make some "internal" feature named binary, it still adds itself (non-uniformly in terms of order) to the re-exported functions. I've made this an issue here because it seems like not too rare of a use-case that makes documenting features so noisy that it becomes unhelpful at-a-glance.

In summary, I can either not inline my re-exports, or deal with unhelpful documented features; it seems like a bug that I can't simply do both, even if it means manually overriding the item at its declaration to say exactly what I want to document.

@Nemo157
Copy link
Member

Nemo157 commented May 3, 2023

It should certainly be possible to simplify be and std and (be or le or varint) to be and std, IIRC there are already some simplifications applied to the cfgs so this would just require extending those. It'd be good to open a separate issue with a small testcase.

@est31
Copy link
Member

est31 commented May 3, 2023

@Nemo157 see #104991

joseluis added a commit to andamira/textos that referenced this issue Aug 29, 2023
- misc. updates.

----
# improve unsafe

- add #Safety section to unsafe functions
- add unsafe sub-features, like in devela THINK

-----------
- Add some pixel fonts a short selection, and option to import
  - (receiving some kind of slice, typed or interpreted
    - (array from one type to another as long as they both implement X
    - (this pattern can be reused throughout all libera

---
- implement From/To Char enum from devela (TODO)

---

- [ ] bring functions from devela
  - strcount
  - buffer fmt
  - strings …

----

- WIP TRY add TryFrom/ From?
  - DESIGN Decide whether to fail, (TryFrom) or return From converting up until capacity.

------
- add new search methods using memchr

----
- add new NulTerminatedString types
  - crate
  - https://github.com/CAD97/cstr8/

- take ideas from other crates
  - https://crates.io/crates/fstr (conversion of just the right size?)

-----

update Egc

- [ ] impl TryFrom Egc (using string) for both static
- … ops

----------

impl From<CharXX> for given string type aliases.

----
update unicode strings

- new type `StaticNonSpecificString`.
- make `StaticNonNulString` a type alias of `StaticNonSpecificString`.

- [ ] TODO generalize strings even more:
  - `StaticNonSpecificString<const CHAR: &str, const CAP: usize> {}`
    - specialize StaticNonNulString as a type alias:
      `pub type StaticNonNulString<const CAP: usize> = StaticNonSpecificString<'\x00', CAP>;`

----
- pop_egc
- push_egc (convenience)

- push_utf8_bytes (from a byte slice) (impl from functions from_utf8?
- pop utf8_bytes?

------
- graphemes? &[egc] ?

----
## IDEAS

chars:

- [ ] new constructor for `Chars` trait and for concrete types.

- add TryFrom<T: Chars>? or as a methods in chars? try_to_XXX

- new char types e.g.: CharMath, CharBoxDrawing
  - those would be... enums :)
    - macro to generate an enum from a list of correspondences.

- [ ] TODO: impl partialEq & partialOrd between all 4 char types

- [ ] TODO: add more constants?
  - [ ] NUL

strings:

- add more alias string sizes? 96 (32×3), 192 (64×3) 384 (128 * 3)

- [ ] MAYBE make counter_string a CounterString trait
  - [ ] impl over String, str, StaticStringU8, StaticNonNullString.

- add non-unicode strings (sixbit?) less bit? with custom translation
  using custom tables. (link to a slice of the specific const-generic size)
- generalize over unicode strings and non-unicode strings… single trait?

------
- TODO: add more methods?
    - escape_unicode
    - escape_debug
    - escape_default

- wrap fns that returns iterators: to_lowercase, to_uppercase
  - https://doc.rust-lang.org/nightly/std/primitive.char.html#method.to_lowercase

----
- make tests, and examples.
- impl push_str & try_push_str & try_push_str_complete for StaticStringU8

----

add indent format

- add own `Align` enum, & impl from fmt::Alignmnent, instead of using that.

-------

- TextCell
- TextGrid (via ladata/Grid2?) to libera type grid2d?? (recuperar cuadra como grid2d?
- TextLine (rows, or
- TextRope
- traits
  - Ascii
  - Utf8
  - Utf16
- struct Str<const BYTES: usize> {} // owns its buffer
-

---

alignment functions WIP examples

- think about using cow

-----
- THINK
  - no_std functions (how to group them)
  - a trait over String?

-------

- THINK alternatives
  - dirty utf versions?
  - stateful struct to customize these things?

-------
## improve box drawing chars

- separate lines
  - add dotted
  - add half
  - add thin to heavy
  - eight vertical & horizontal lines (U 15)
  - diagonal lines (U15)

- add block elements
  - shades
    - half block shades
  - quadrants
  - sextants
  - eight vertical & horizontal blocks
  - eight vertical & horizontal blocks upper & right (u15)
  - corners
  - diagonal blocks (U15)

- add a binary encoding

----

-----
## alt. unicode-width
- add an opinionated wrapper over unicode-width
  - maybe create traits depending on UnicodeWidthStr / UnicodeWidthChar
    - save custom tables for special symbols
    - for the rest of symbols, derive to unicode-width
  - deal with >2 width chars
  - deal with https://github.com/unicode-rs/unicode-width/issues/

----

- From rational to select unicode char on filling

--------------

I want to provide scaffolding for apunta bin + revela lib)
a text buffer that refreshes, that can be analized, strings positioned…
areas detected, layers... analisys at certain frequency / Hz

---

- refactor cargo manifest

----
# functions beneficial to implement in a Rust library for text manipulation

- https://chat.openai.com/c/17b13959-8073-42ef-bcf4-0b9ef59eb97c

-----------
# rope
- example crop

alternatives
- https://docs.rs/crop
- https://docs.rs/jumprope
- https://docs.rs/ropey/*/ropey/struct.Rope.html
- https://docs.rs/any-rope/*/any_rope

----

# TODO
- unicode columns based on width + override specially long characters
  - (perfect ad-hoc hash-map associated)
  - https://github.com/AldaronLau/unicode-columns/blob/stable/src/lib.rs

-----

# UNICODE BLOCKS
- https://docs.rs/unicode-blocks/0.1.5/unicode_blocks/struct.UnicodeBlock.html

- `block` module. re-export crate.
- desired API:
  'a'.block() -> UnicodeBlock
  UnicodeBlock.name()
  UnicodeBlock.start()
  UnicodeBlock.end()
  UnicodeBlock.contains('a')

------

# UNICODE SEGMENTATION
- https://unicode-rs.github.io/unicode-segmentation/unicode_segmentation/index.html

------

# mixed blitter
- dankamongmen/notcurses#1223

----

add collections of unicode characters with metadata

- allow to support pixel ttf fonts, etc...

- e.g.: dots: … ‥ . · etc…

codepages
- https://crates.io/crates/codepage-strings
- https://crates.io/crates/oem-cp

# IDEAS
- recreate sixbit, in a more general way… choosing bw 64 & 128-bit codepages
  - https://crates.io/crates/sixbit/

--------
- no_std formatting?
  - https://doc.rust-lang.org/core/macro.format_args.html
  - https://doc.rust-lang.org/core/fmt/struct.Arguments.html

--------
- ASCII utilities
  - see: https://doc.rust-lang.org/std/ascii/trait.AsciiExt.html#tymethod.eq_ignore_ascii_case

---
- CASE utilities
  - https://stackoverflow.com/questions/38406793/why-is-capitalizing-the-first-letter-of-a-string-so-convoluted-in-rust

# ISSUES
- "Available on non-crate feature `safe` only."
  rust-lang/rust#43781 (comment)

## FONTS (TODO move to `trazas` crate?)
- https://news.ycombinator.com/item?id=34689213

# LEARN FFI cstring, etc.
- https://www.reddit.com/r/rust/comments/s3x1e3/const_const_u8/
  - u8 is always 8-bits, but it's a mistake to use u8 rather than std::os::raw::c_char

# LEARN unicode
- https://unicode.org/glossary/#byte_order_mark
- https://en.wikipedia.org/wiki/Homoglyph#Unicode_homoglyphs

# CRATES

- https://github.com/bcmyers/num-format (also for numera, ladata…)
- > https://docs.rs/memchr/2.5.0/memchr/

- https://crates.io/crates/texcore
- https://crates.io/crates/tectonic  :) a complete TeX/LaTeX engine

- https://crates.io/crates/character-set (for inspiration) (source not in github)
  - https://docs.rs/crate/character-set/0.4.0/source/src/builtin/general_category.rs

# WAITING for
- https://doc.rust-lang.org/nightly/core/ascii/enum.Char.html
  - rust-lang/rust#110998

- rust-lang/rust#109814 string.leak for 1.72.0

## DISCARDED IDEAS

- [ ] remove Char types, move to devela?
  - better not, because I need good trait coupling…
@GuillaumeGomez
Copy link
Member

We'll need #103300 to be fixed beforehand as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
B-unstable Implemented in the nightly compiler and unstable. C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. F-doc_auto_cfg `#![feature(doc_auto_cfg)]` F-doc_cfg `#![feature(doc_cfg)]` T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
Status: Idea