Usage of QualName is not well documented

[kornelski]

The documentation explains well what is the local name in general from HTML/XML perspective, but doesn't say anything about its usage in this particular Rust implementation. For example:

• How to get the name as &str?
• How to compare the name against several names in match?
• How to create a new one? new() says it's a "Simple constructor function.", but it's absolutely not simple, because it requires an instance of a peculiar Atom<LocalNameStaticSet> type.

Atom, StaticAtomSet, and PhfStrSet are not re-exported in the crate, so I can't see their documentation.

There's LocalNameStaticSet::get() that appears to return something string-like, but when I call qualname.local.get() it seems to match a different method (on Atom?) that requires an undocumented argument.

[SimonSapin]

Yes, the doc’s prose could definitely be improved here.

It’s somewhat unfortunate that when the type of a field is a type alias, rustdoc doesn’t show the alias’s name. These are relevant here:

• https://docs.rs/html5ever/0.22.5/html5ever/type.LocalName.html
• https://docs.rs/html5ever/0.22.5/html5ever/type.Namespace.html
• https://docs.rs/html5ever/0.22.5/html5ever/type.Prefix.html
• https://docs.rs/html5ever/0.22.5/html5ever/macro.local_name.html
• https://docs.rs/html5ever/0.22.5/html5ever/macro.namespace_url.html
• https://docs.rs/html5ever/0.22.5/html5ever/macro.namespace_prefix.html
• https://docs.rs/html5ever/0.22.5/html5ever/macro.ns.html
• https://docs.rs/html5ever/0.22.5/html5ever/macro.expanded_name.html

The macros return values of the corresponding type, and are usable in patterns (in match) as well as in expressions. When matching or comparing for equality though you might want to ignore the prefix (which is not semantically significant in XML) and use the .expanded() method and expanded_name!() macro.

QualName::new is simple in its behavior (same as a struct literal), if not necessarily its usage.

Atom is from the string_cache crate and implements Deref<&str>.

LocalNameStaticSet is an implementation detail of the string_cache crate that ideally would not appear at all in public API docs.

[Ygg01]

I'd be up for updating the docs. To clarify, is this the definitive list of additional docs?

• Get &str from local_name
• Using match and Atoms?
• Example of creating a QualName (is using macros ok?)

[kornelski]

@Ygg01 Yes, that would be very useful. It'd also be good to re-export the types in this crate, so that rustdoc can show them.

[Ygg01]

@kornelski Hi, I've done examples of usage of &str from local_name, explained the QualName::new, and added extra QualName::expanded comments.

I'm unsure where do you expect to find the usage of match on Atoms docs?

I apologize for the late reply, I was busy with regular work, but expect a PR today.

[kornelski]

Thank you for adding it.

Example with LocalName::from solves my question on how to create them.

I asked about Atom, because it's an opaque type in the docs (docs.rs doesn't link to its description), so I couldn't see how to use it. From the examples I can guess it implements deref to &str, so that answers my question.

[Ygg01]

@SimonSapin is there a way to link to Atom documentation on docs.rs or is reexporting the preferred choice?

Hm. In hindsight maybe macros will need more docs. I'll probably copy paste them from QualName docs.

[jdm]

There are now docs related to QualName.