[Development] Make qdoc an officially supported tool for generating QML API documentation

[casper.vandonderen at nokia.com]

On 6/11/12 11:48 AM, "ext Sven Anderson" <Sven.Anderson at snom.com> wrote:

>Hi Casper,
>
>On 11.06.2012 10:32, casper.vandonderen at nokia.com wrote:
>> We have been very busy to get qdoc running outside of Qt (I am starting
>>to
>> use qdoc as LaTeX-lite now if I just need an HTML page). I do agree that
>> the qdoc manual should be improved with examples that do not necessarily
>> reflect how we use qdoc with Qt.
>
>thanks for your reply. That's good news! So, this sounds like "Yes, qdoc
>will probably be an official tool for external usage". Is this
>interpretation correct?

Well, "official" and "external" are pretty big terms, I do not see myself
packaging qdoc with a separate installer just yet. The build dependency to
Qt will obviously not go away, and the needs for the Qt Project will
always stay a requirement. But I do not see us (read: "the Qt community")
having qdoc as a tool that we ship for others to use and file bugs against
as a problem (maybe others have different opinions)

>> All changes that we are doing to qdoc are only added to the Qt5 version
>>of
>> qdoc (which is qdoc instead of qdoc3). The Qt5 version should also
>>support
>> the \inherits you mentioned in the QTBUG (be aware that you cannot use
>> \inherits when documenting .qml files, since we automatically use the
>>top
>> level element in the .qml file.
>
>That's great! In the the docs for qdoc (Qt 5) it's not yet mentioned how
>\inherits behaves on "external" QML items. So, how does it work? Does it
>have a hardcoded list of Qt Quick items and its elements and links it to
>the official Qt Quick docs? Or will it even work with third-party QML
>items? But then, where does qdoc get the information about inherited
>members and the location of their documentation?

For every qdoc run a .index file is generated, this .index file can then
be used with the "indexes" qdocconf variable, or play around with the
"depends" variable in combination with the -indexdir and -installdir
command-line options. The depends variable takes a comma-separated list of
documentation runs to link to, for example "depends = qtcore, qtgui" to
link to the Qt Core and Qt GUI documentation. The command-line arguments
are mostly undocumented, an example can be found in qtbase, since running
"make docs" in qtbase uses all of these options together to get modular
documentation.

We have removed some of the hard-codedness that was still in qdoc, but one
thing that is recently added and completely hard-coded is how the depends
variable is handled inside qdoc. QDoc only searches for [depends
variable]/[depends variable].index under the directory specified with
-indexdir. 

I had not really expected others to want to use qdoc just yet, but I think
a healthy discussion about the future should take place at some point.


Casper