[Development] Documenting JavaScript with QDoc

[Reinio Topi]

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

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
*/

And go from there. Hope that helps!

-Topi

> 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
>
> -- 
> Qt Developer Days 2014 - October 6 - 8 at BCC, Berlin
>
> 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