[Development] Documenting JavaScript with QDoc

Milian Wolff mail at milianw.de
Thu Apr 24 15:55:30 CEST 2014


On Tuesday 22 April 2014 11:00:09 Reinio Topi wrote:
> > Hello!
> > 
> > I'm trying to add documentation to the JavaScript API of QWebChannel. It
> > is a fundamental part of this module and as such, I think proper
> > documentation is crucial.
> > 
> > So far, I have not found a way to get qdoc to generate a page for my .js
> > file for me. Can it? Or do I have to create a separate .qdoc file, and -
> > if so - what commands to I need to use in that file?
> 
> qdoc can parse .js files, however the terminology it uses in the html output
> is more geared towards QML type documentation. That said, you can see how
> it looks like - by default, .js files are not parsed for documentation
> comments, but you can enable it by adding a line
> 
> sources.fileextensions += "*.js"
> 
> into your .qdocconf. No need to use separate .qdoc files or dummy .cpp
> files.

Hm, I tried this but the next issue that I have a C++ "QWebChannel" class and 
a JavaScript QWebChannel. Thus I get:

warning: "QtWebChannel" Cannot locate index file for dependency "qtwebsockets"
/ssd/milian/projects/qt5/qwebchannel/src/webchannel/qwebchannel.js:57: 
warning: Overrides a previous doc
/ssd/milian/projects/qt5/qwebchannel/src/webchannel/qwebchannel.cpp:53: 
warning: (The previous doc is here)

Is QDoc even able to understand that the following is considered a class 
(following the constructor function pattern)?

var foo = function()
{
  ...
};
 
> Also, although not strictly required, any \qmltype should belong to a
> \qmlmodule. Even though this is abusing the qdoc commands a bit, you
> could try something like:
> 
> /*!
>     \qmlmodule qwebchannel.js
>     \title Qt WebChannel JavaScript API
> */
> 
> /*!
>     \qmltype foo
>     \inqmlmodule qwebchannel.js
> */

Yes, this brings me a bit further than before. But the output is far too QML 
specific. It e.g. lists an "Import Statement: import qwebchannel.js" which is 
of course not what I want for a JavaScript file which should be included in 
HTML clients...

So I think I'll stick to the \page approach and just document everything in 
textual form there. Not nice, but better than the alternatives, apparently.

Thanks for the help Reinio!

> > I tried something like this:
> > 
> > /*!
> > 
> >     \title Qt WebChannel JavaScript API
> >     \page javascript.html
> >     
> >     To communicate with a QWebChannel or WebChannel, any HTML client must
> >     use
> > 
> > and setup the
> > 
> >     JavaScript API provided by \c qwebchannel.js.
> > 
> > */
> > 
> > /*!
> > 
> >  \qmltype foo
> >  
> >   asdfsadf
> > 
> > */
> > 
> > /*!
> > 
> >  \qmlmethod bool foo::test();
> >  
> >   foo bar
> > 
> > */
> > 
> > On the javascript.html page, I then cannot see anything about foo nor
> > foo::test... Is there maybe a module out there which documents "pure" .js
> > files? In QtDeclarative, I only found documentation for  .cpp/.qml
> > functions so far. Even things like qsTr are actually documentation for a
> > .cpp method which gets renamed using \qmlmethod...
> > 
> > Hope anyone can help me here. The only potential workaround I could think
> > of so far would be adding a dummy .cpp file for the documentation of the
> > .js API of the QWebChannel.
> > 
> > Thanks
> > 
> > 
> > Milian Wolff | milian.wolff at kdab.com | Software Engineer
> > KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
> > Tel. Germany +49-30-521325470, Sweden (HQ) +46-563-540090
> > KDAB - Qt Experts - Platform-independent software solutions
> 
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development

-- 
Milian Wolff
mail at milianw.de
http://milianw.de



More information about the Development mailing list