Add documentation for the public API

[aperezdc]

Probably we would want to use GTK-Doc, which despite the name does not need GTK+ at all. That would allow cross-linking to the WPE WebKit API reference if needed.

See also https://github.com/WebPlatformForEmbedded/libwpe/issues/37 and BWO#178900.

[philn]

Or Hotdoc?

[aperezdc]

@philn Is that this HotDoc? I didn't know about it, looks like a good option as well!

[philn]

Yes! GStreamer is migrating to it as well.

[In-vincible]

@aperezdc is this issue up for grabs from beginners? If yes, please provide me with some more help about how to start with the work.

[aperezdc]

@In-vincible Some help documenting the public API would definitely be appreciated. The tricky bit is to have the support for building the documentation; I have just posted #29 to wire HotDoc into the build system, once that patch merged, you should be able to do:

cmake -DBUILD_DOCS=ON
make Documentation
xdg-open Documentation/html/c-index.html 

Once that is working, you can start adding documentation next to function declarations using the GTK-Doc syntax (HotDoc uses the same syntax for C code), and re-run make Documentation to regenerate the HTML pages with your changes.

Please do ask if you need some more help from that point on, and remember that you can find us in the #webkit channel in the Freenode IRC :wave: