[Development] No implementation hints in Qt Documentation

[Thiago Macieira]

On quinta-feira, 3 de maio de 2012 12.18.47, Pierre Vorhagen wrote:
> I regularly find myself browsing and grep'ing through the source tree to
> find the implementation of a given class, referenced in the Qt
> Documentation. Of course, as a newbie to Qt internals, I don't yet
> intuitively know where all the classes are located.

Aside from the module name, the organisation is pretty much arbitrary. It 
might have made sense when the organisation was put into place, but those 
reasons may or may not be valid now, given changing circumstances and files 
being added.

I know where classes are in QtNetwork and QtCore, but whenever I need to find 
something in QtGui or QtWidgets, I use wildcards. To top that, the unit tests 
are organised in a similar-but-not-exactly-the-same way.

> I find that the insight into the implementation of an API to be one of
> the major strong points of open source frameworks, because it not only
> gives a better understanding of how to use the function, it also helps
> greatly in avoiding problems that become obvious once you see what lies
> beneath. Although the docs are generally very helpful as is, and may be
> enough for some programmers, I think it would be an addition of great
> value to enable quicker access to implementations from the docs. This
> could be done via a direct hyperlink to the implementation, I think
> doxygen has such a feature, but I think that even a simple
> path/to/the/implementation would already be a great thing. (In Java, for
> instance, this is naturallly present with the java.util.path.to.package
> scheme.)

Qt didn't use to have a publicly accessible official version of the source code, 
so qdoc wasn't designed for that.

In any case, the documentation is what's valid. If the code and the 
documentation differ, usually the documentation prevails and the code needs to 
be changed.

I'm not saying the documentation will always be enough. But it should be good 
enough for the vast majority of the cases, so looking into the source code 
should not be necessary. At least, not while you're writing your own code -- 
if you're debugging, that's another story. For that reason, I think that 
adding links to the documentation would unnecessarily clutter it and might 
even confuse some people.

> 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.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
     Intel Sweden AB - Registration Number: 556189-6027
     Knarrarnäsgatan 15, 164 40 Kista, Stockholm, Sweden
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120503/34db40d3/attachment.sig>