search

woboq / qmetaobject-rs

Integrate Qml and Rust by building the QMetaObject at compile time.
MIT License
641 stars 89 forks source link

Proposal: qt_doc macro #88

Open ratijas opened 4 years ago

ratijas commented 4 years ago

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

:exclamation: 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 commented 4 years ago

Candidates are: qt_doc and qt_doc_comment.

i'd go with qt_doc_comment

ratijas commented 4 years ago

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. https://github.com/dtolnay/quote/issues/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

Screenshot_20200505_195257 Screenshot_20200505_192704

ratijas commented 4 years ago

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

ogoffart commented 4 years ago

I created the qt_doc branch

ogoffart commented 4 years ago

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

ratijas commented 4 years ago

(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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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: