Rustdoc needs to handle conditional compilation somehow

[brson]

We have some functions that are reimplemented per architecture, with docs only on one implementation. Rustdoc should ideally be able to merge these docs.

More seriously though a bunch of our libc hierarchy can't be viewed because it's conditionally compiled and the docs are built on linux.

Probably rustdoc should extract its documentation before pruning the AST for conditional compilation, collapse things with the same name into a single document, then run resolve.

[graydon]

I think the latter case is probably best, yes. Collapse-same-name is a bit of a kludge but not entirely unexpected.

[catamorphism]

Not backwards-compatible. Nominating for milestone 4, well-covered (having documentation tools work the way we expect is helpful in making sure the documentation covers everything...)

[graydon]

doc-coverage can be assured elsewhere, but this is embarrassing. should be fixed before production ready.

[graydon]

accepted for production-ready milestone

[msullivan]

Nothing new to say except to link to #5413.

[emberian]

#8125

This is not yet fixed by rustdoc_ng, and requires a bit of thought.

[emberian]

This is a hard problem with no good solution. If I use the AST before configuration, I can't have any hyperlinking for those items. Is that worth it?

[catamorphism]

Low, no milestone

[emberian]

My current thinking:

1. Parse, get unexpanded, unconfigured AST
2. Pull out everything cfg'd with the same name into sidetable
3. Configure, expand.
4. Pull out everything with the same name again.
5. Run rest of core.

Then, later, when cleaning, check if the item's nodeid is in the sidetable of cfg'd things. If so, add them to a vec of "alternatives" in the item, cleaning each.

This depends on:

1. The AST never being renumbered. (I don't think this is true today? @pcwalton?)
2. Holding onto a reference to the pre-expanded AST will cause that node to still be alive later on, but not otherwise affect the AST. (I think this is true today.)

When rendered, we'd have a list of "alternative definitions", listing the cfg's that would have enabled them. This of course doesn't handle things that are actually conditionally enabled/disabled, just things that are defined multiple times.

[pcwalton]

I'm not sure about AST renumberings off the top of my head.