on documentation

[David nolden]

Am Samstag 31 Januar 2009 17:13:56 schrieb Aleix Pol:
> hi list!
>
> I was thinking on kdevelop 4's documentation support. I've been checking
> some of the code we have in playground. It is quite disappointing to see
> that much of the code there is just oriented to support many many
> documentation formats but real actual integration.
>
> I think it would be nice to have proper integration support. For now
> doxygen and qt assistant would be nice, or maybe just assistant (since most
> of it could be used by getting it from Qt's assistant, QHelpEngine).
>
> What I think it would be important would be that this documentation support
> could be (easily) integrated with the DUChain. That would mean to be able
> to identify classes and method names and relate them to the proper
> documentation pages and show c++ reference if using c++ and Qt, and pyqt's
> doc if using python.
>
> What do you think about it? Is there any work to do so already done?
>
> Thanks,
> Aleix

I think the first most important thing is, as you say, integration with the 
duchain.

For the start, we could just have something like this:
class IDocumentation : public KShared, public QObject {
//Should return a short version of the documentation
virtual QString html() = 0;
virtual KSharedPtr<IDocumentation> executeLink(QString link);
//Should open this documentation within an own part within KDevelop
virtual void showSeparateDocumentation();
Q_SIGNALS:
//Can be usd to signalize that new documentation is available(maybe downloaded 
from the internet)
void documentationFetched();
};

class IDocumentationPlugin {
//Should return 0 if no documentation for the declaration is available from 
this plugin
virtual KSharedPtr<IDocumentation> 
documentationForDeclaration(KDevelop::Declaration* declaration) = 0;
};

Then we could start implementing different documentation-provider plugins one 
by one. The first one we really need is one for Qt, since Qt does not have any 
in-header comments. The main question is how to get the relevant information.

The navigation-widgets could just query for all plugins implementing 
IDocumentationPlugin, and try getting documentation from them.

Greetings, David