Proposal: qt_doc macro

[ratijas]

This is a tracking issue for a macro that expands to a doc comment with links to Qt's documentation website.

• Choose a name.
  Candidates are: qt_doc and qt_doc_comment.
  Less typing is usually better, but we shall not sacrifice readability.
• Basic working PoC: ratijas@df56779
• Implement different member types (e.g. cls, method, signal etc.)
• Enum variants
• Struct public members
• The ultimate goal: #![deny(missing_docs)]
• Implement custom doc-comment (add it after # Implementation details header)
• Re-write all existing doc-comments of wrappers
• Tracking bug in proc_macro ecosystem: Adding #[meta] to an item in a TokenStream dtolnay/quote#153
• Extracting docstrings from real Qt docs web pages ❗
• Integration with qch (see comment) ❗
• Open-ended questions:
  • Qt6 links (when it is out)?

❗ Mutually exclusive quests

(I don't feel like managing stuff and writing contributing guidelines at the moment. So, I thought I'd better start with some straightforward implementations.)

I'm gonna do it step-by-step, pushing onto separate branch of its own. syn, quote and darling crates should do most of the job, but still this task is composed of several smaller ones.

[ogoffart]

Candidates are: qt_doc and qt_doc_comment.

i'd go with qt_doc_comment

[ratijas]

I wonder, am I that lucky? Stepped into proc macros world for the second time in my life, and right away found another funky bug. dtolnay/quote#153

UPD

Apparently, that was a bug in a compiler; it was fixed in the latest stable 1.43.0; and there is a really simple workaround for older versions.

Now it's good

[ratijas]

@ogoffart Could you please create a branch, so I won't make PRs against master until it's finished?

[ogoffart]

I created the qt_doc branch

[ogoffart]

(btw, i've given you write access to the repository)

[ratijas]

(btw, i've given you write access to the repository)

Oh, thanks. That's an honor for me. Hope I would live up to your expectations and won't let you down.

[ratijas]

I looked closely on the alternative bindings providers, and found Ritual's approach somewhat interesting. The interface itself is an over-complicated mess of generics and double-colons, and by no means is a code that a human would want to read/write even instead of using C++. However, I don't intend to understate their importance, because there's still much to learn from them and their research.

For example take a look how Qt documentation is embedded in every single entity. Looks like straight-forward copy-paste HTML from the website, but still impressing! I see how qt_doc could benefit from it. We could make a script which greps all rust sources looking for macro invocations, extracts the URL path from them, downloads all referenced pages, stores into cached directory (or maybe parses individual entities further and stores in a structures database), so then the macro itself loads the official documentation at build time and adding it to the items it processes. Of course, such cache should either be provided with repository or be not strictly required to build the crate.

[ratijas]

I have just checked, and it appears #[qt_doc(...)] attribute plays nicely with #![deny(missing_docs)].

The next question is enum members, since missing_docs also requires having docs on each and every enum variant. For now, I'll add this to the TODO list on top.

[ratijas]

Qt theoretically ships documentation in their own *.qch format which simply is a well-structures SQLite3 database. Unfortunately, I didn't find any official releases, but builds from source are still possible.

So I searched around, and found Ubuntu package qt5base-doc. Archive size looked promising (about 26 MB) but to my surprise it only actually contains headers and titles, and most of it is FileDataTable with big BLOBs of content. It doesn't look like UTF-8 or UTF-16; probably some sort of compression applied. Anyway, there are certainly qt-doc tools out there, so we don't need to touch those qch databases directly.

TODO:

• Investigate possibility, pros and cons of inclusion of pre-build qch docs in qmetaobject distribution
• Investigate licensing (in case of redistribution of docs)
• Investigate qch tooling. More importantly: extracting docs based on entity name / type / signature.