QDoc not generating code for overloaded static method

[sierdzio]

Hi!

As those of you following Qt5-feedback may know, I am currently writing QWebService. All's going well, except one detail I encountered:
in QDoc, \overload does not seem to include a static overloaded method. It also refuses to include it in generated doc when I declare it as a separate \fn. No errors are reported. Any thoughts on solving that? Or maybe it's a bug/ feature ( :) )?

Below, I post relevant part of the code, full source (including resulting QDoc) can be found at https://gitorious.org/qwebservice

@
/*!
\fn QWebMethod::sendMessage()

Sends the message asynchronously, assuming that all neccessary data was specified earlier.
Returns true on success.

\sa setParameters(), setProtocol(), setTargetNamespace()

*/
bool QWebMethod::sendMessage()
{
// Body. This gets included in QDoc.
return true;
}

/*!
\overload sendMessage()

Sends the message asynchronously using parameters specified in \a params.

*/
bool QWebMethod::sendMessage(QMap<QString, QVariant> params)
{
// Body. This also gets included in QDoc.
return true;
}

/*!
\overload sendMessage()

 STATIC method. Sends the message synchronously, using \a url, \a _messageName, \a params and \a parent.
 Protocol can optionally be specified by \a protocol (default is SOAP 1.2), as well as HTTP \a method
 (default is POST).
 Returns with web service reply.

*/
QVariant QWebMethod::sendMessage(QObject *parent, QUrl url,
QString _messageName, QMap<QString, QVariant> params,
Protocol protocol, HttpMethod method)
{
// Body. Yes, return type is different than in other methods. QDoc does not include that method.
}
@

[dangelog]

How does QObject::connect do it? :)

[sierdzio]

I've tried making it similar to QDoc in QObject, thanks for the hint. But it still does not work. The only difference is that I at least get an error message:

@
./sources/qwebmethod.cpp:308: Cannot find 'sendMessage(...)' in '\fn'
[I cannot find any function of that name with the specified signature. Make sure that the signature is identical to the declaration, including 'const' qualifiers.]
@

For code (I've also tried many other combinations, to no avail):
@
/*!
\fn QVariant QWebMethod::sendMessage(QObject *parent, QUrl url, QString _messageName, QMap<QString, QVariant> params, Protocol protocol, HttpMethod httpMethod)
\overload sendMessage()

 STATIC method. Sends the message synchronously, using \a url, \a _messageName, \a params and \a parent.
 Protocol can optionally be specified by \a protocol (default is SOAP 1.2), as well as HTTP \a method
 (default is POST).
 Returns with web service reply.

*/
QVariant QWebMethod::sendMessage(QObject *parent, QUrl url,
QString _messageName, QMap<QString, QVariant> params,
Protocol protocol, HttpMethod method)
{
// Body.
}
@

[sierdzio]

I've checked the code today, and it still does not get generated... Not a big problem for me, as I know the method is there, but other people may have problems with that.

I've removed the "\fn" statements in the code, it has not helped this case. Method is now located in "QWebServiceMethod":https://gitorious.org/qwebservice/qwebservice/blobs/master/QWebService/sources/qwebservicemethod.cpp class. The resulting doc file can be found "here":https://gitorious.org/qwebservice/qwebservice/blobs/master/QWebService/html/qwebservicemethod.html. All other docs are generated without problems (well, almost. QDoc seems to also be quite selective when it comes to Q_PROPERTY documentation).

[andre]

Perhaps you can bring this up at the qt-project development mailinglist? I think QDoc should be properly documented and maintained for non-nokians to be able to make decent, documented ccode ontributions. Perhaps a move to doxygen could even be considdered?

[sierdzio]

Might be a good idea, thanks.

I think doxygen was being discussed back in the qt5-feedback days, and was voted down on the basis of it being to much work to transfer. There were some problem with using it for QML, too. Not that QDoc performs there amazingly, it seems to have undergone extensive hacking to allow Qt Quick documentation.

Anyway, thanks, I think I will raise the subject on development-request soon(-ish).