[Development] No implementation hints in Qt Documentation

[casper.vandonderen at nokia.com]

On 5/3/12 12:30 PM, "ext Thiago Macieira" <thiago.macieira at intel.com>
wrote:

>>
>>This is something that integrates well with the open governance concept
>>too, as I think that there's still a considerable gap between users and
>>contributors of Qt. Maybe this is something to consider in order to
>>narrow it a little more.
>
>Casper, as the documentation and qdoc maintainer, should have a say,
>probably
>the final say.
>
>There's also another option, which is to have a "Qt developers
>documentation",
>probably matching the next unreleased version of Qt. That way, we, the
>developers, can easily locate the source code when proof-reading our
>documentation and verify that it does what it says it should do.

Some thoughts have been put into this already. We could easily add a
-developer CLI option to QDoc.
The biggest problem I'm seeing is detecting the correct path and location
in that file when building the documentation.

Just as some qdoc trivia:
- QDoc internally changes directory to the directory containing the
qdocconf file you are running on.
- QDoc only knows the location of the documentation, and not the actual
location in the file where the documentation is.

Real-life example concerning QTimer:
In qtbase/src/corelib/kernel/qtimer.cpp:177 we have \fn bool
QTimer::isActive() const
That function is an inline function in the header.

What qdoc currently can do is print: ../kernel/qtimer.cpp:177
Which does not buy anyone anything, since you still need to know where the
kernel folder is.
So then we should probably use the full path to the file, but then
publishing it won't make that much sense. (it would be
/home/docbuild/qtbuild/5.0-snapshot/qt5/qtbase/src/corelib/kernel/qtimer.cp
p)

If that is good enough: you can implement it in qdoc, I will gladly review
your patches ;-).


Casper