anders429 / doc_item Goto Github PK

A failure on the frontend test should open a new issue on GitHub. There are some actions on the marketplace to do this.

It should only be done on scheduled runs. PRs and pushes should not open issues when they fail.

The other day I switched the crate from depending on uuid to instead using a globally-incremented value (protected by a Mutex). Upon further research, I think it is best to switch back to uuid.

It seems that sharing state in proc_macros is not generally recommended. Additionally, if execution were to be done in a multi-threaded context (which I don't think is possible right now, but may be in the future?), the Mutex would cause blocking, which would slow things down. Additionally, using the Mutex requires a dependency on once_cell (or alternatively, lazy_static), which means the dependency count doesn't actually change much.

uuid is probably the best choice, since the ID just needs to be unique for short docboxes. A uuid is the best solution for getting a unique ID with the least amount of strings attached.

Each attribute could potentially be used as an inner attribute.

#![doc_item::since("1.28.0")]
#![doc_item::docbox(content = "...")]

The above code block could be used at a crate-level to define crate-level since and item-info values.

As far as I can tell, the main challenge will be identifying whether the attribute is in an inner or outer position. The way to tell seems to be to check for pub mod { ... }. As I understand, pub mod {} is not valid in any other context, and is only wrapped around the full crate's code. As far as being used as an inner-attribute in other contexts, that may require more investigation surrounding what is passed in as the item TokenStream.

Note that this usage would require nightly, with custom_inner_attributes enabled.

The frontend test is failing on nightly. The issue seems to be with the rest, rather than with the code. The default tags in the documentation have changed, but it seems that the actual doc item stuff still works.

I will try to find a related PR for what changed and see if I can roll out a fix for the tests.

The current HTML/JS strings are totally unreadable as they are (all one line) and are hard to work with when editing. The current one-line-ness of them is due to wanting the inserted snippet to be as short as possible.

It might make more sense to have the values listed out fully, and use an HTML minifier instead.

CI started failing on the frontend test a couple of days ago. It corresponds with this change on the rustdoc side: the character "⎘" was added after item names in the headers, allowing users to copy the item's relevant use path.

Cool change, it just breaks the doc UI test. No actual attribute code needs to be changed. An easy fix would be to use something like substring to just grab the first n characters and match those.

No release should be necessary to resolve this.