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
Comments
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.
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.
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.
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.
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.
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.
|
I think that |
There is also the issue that it repeats every feature on every item in a page: 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. |
…c, r=QuietMisdreavus Stabilize cfg(doc) cc rust-lang#43781.
We tried out this feature in Syn (dtolnay/syn#734) and decided against using it yet. What I am happy withI 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 withOur 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. |
As a reminder, this is a tracking issue for stabilizing As far as I can tell, the current status is that the stabilization PR (#100883) is blocked on deciding whether |
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. |
Since I see an RFC is being written, I take the opportunity to share my case, since I wanted to use This does result in: "Available on feature
But this results in: "Available on non-crate feature
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. |
Should the original post link to #100883 instead? |
I'm running into a rather annoying problem with documenting features. I am writing currently a Of course, I tried with 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 ( |
|
I believe I understand this is stylistic, but every 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. |
It should certainly be possible to simplify |
- 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…
We'll need #103300 to be fixed beforehand as well. |
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 thedoc_auto_cfg
feature introduced in #90502.Steps:
Fix syntax mismatches: Rustdoc and rustc accept different(fixed in Unify rustc and rustdoc parsing ofcfg
syntax #84437cfg()
#84442)(cc #1998)
The text was updated successfully, but these errors were encountered: