Stream: rustdoc

Topic: Prepresentation of associated constants


view this post on Zulip HeroicKatora (Jan 24 2021 at 14:46):

Constants declared in the impl of a struct use the AssocConstant form, not ConstantItem. That's not particularly useful because the former has an optional default but in impls a definition is required very similar to an actual constant declaration. Also, the definition of an associated type in an impl is a TypedefItem and not an AssocTypeItem as expected.

Compare the output:

pub trait EasyToImpl {
    /// A type that must be declared.
    type ToDeclare: Clone;
    /// A method you do need to impl.
    fn method_to_impl(&self);
    /// A provided method you do not need to impl.
    fn method_not_to_impl(&self) {}
}

struct Simple;

/// This inherent impl:
impl Simple {
    pub const CONSTANT: usize = 0;
}

/// versus this trait impl
impl EasyToImpl for Simple {
    type ToDeclare = usize;
    fn method_to_impl(&self) {}
}

view this post on Zulip Joshua Nelson (Jan 24 2021 at 14:47):

@HeroicKatora I love that you're finding all rustdoc inconsistencies :laughing: are you interested in a PR to fix it?

view this post on Zulip Joshua Nelson (Jan 24 2021 at 14:47):

this is a problem with the internal representation too, it duplicates lots of types

view this post on Zulip HeroicKatora (Jan 24 2021 at 14:51):

Not sure if I can make the time besides working on my own toolings, particularly if it affects the internals too (and probably has effects quite spread out over the code base then?)

view this post on Zulip Joshua Nelson (Jan 24 2021 at 14:53):

probably yes

view this post on Zulip Joshua Nelson (Jan 24 2021 at 14:53):

ok, can you open an issue then?

view this post on Zulip HeroicKatora (Jan 24 2021 at 15:10):

https://github.com/rust-lang/rust/issues/81340

view this post on Zulip Joshua Nelson (Jan 24 2021 at 15:11):

thanks :) btw I think the JSON output would be more helpful than the debug output, it's more concise at least

view this post on Zulip HeroicKatora (Jan 24 2021 at 15:17):

Sure, let's update that.

view this post on Zulip HeroicKatora (Jan 24 2021 at 15:19):

Okay, I need to set no_std and no_core for actually compact output

view this post on Zulip CraftSpider (Jan 24 2021 at 23:34):

Wonder if there would be a use for some way to tell JSON to only output things defined in the current crate, even if just for debugging

view this post on Zulip CraftSpider (Mar 29 2021 at 22:54):

Working on fixing this now. Leads to an interesting question of whether there should be more info in associated items about what item is their 'parent', it doesn't look like that info is readily available in the JSON currently? Unless I'm missing something not in the paths or items maps

view this post on Zulip Joshua Nelson (Mar 29 2021 at 23:12):

CraftSpider said:

Wonder if there would be a use for some way to tell JSON to only output things defined in the current crate, even if just for debugging

I think you could do this with a JQ filter

view this post on Zulip Joshua Nelson (Mar 29 2021 at 23:18):

hmm it turned out to be kind of tricky, I want to say "any key" but I don't know how to do that

view this post on Zulip CraftSpider (Mar 29 2021 at 23:59):

.index |= [.[] | select(.id | startswith("0:"))] | .paths |= with_entries(select(.key | startswith("0:"))) seems to roughly do the correct filtering

view this post on Zulip CraftSpider (Mar 30 2021 at 03:17):

So, roughly where I stand:
I can swap it over to using constant fairly easily. The issue is then that HTML gets messed up, because it renders the same as a normal constant. This is basically because AssocConstItem/ConstantItem were not designed to actually parallel AssocTypeItem/TypedefItem when implemented.

view this post on Zulip CraftSpider (Mar 30 2021 at 03:17):

I'm learning a lot diving into the guts of HTML rendering and how rustdoc handles this stuff :P

view this post on Zulip Joshua Nelson (Mar 30 2021 at 09:06):

Yeah the hard part of this is getting the html to have the same behavior

view this post on Zulip Joshua Nelson (Mar 30 2021 at 09:06):

I think I remember trying something similar for TypedefItem and it breaking Deref impls or something


Last updated: Oct 11 2021 at 22:34 UTC