Hello, GTK+ port is currently missing the gtk-doc generated documentation.
Created attachment 18737 [details] gtk-doc makefile This is a very tweaked GNUmakefile for generating docs with gtk-doc. What you have to do is to put the GNUmakefile inside WebKit/gtk/docs then type make from inside the docs directory.
Created attachment 19701 [details] Add gtk-doc build infrastructure. Here's an alternate implementation for setting up the infrastructure, following more closely how gtk-doc is intended to be used (gtkdocize, Makefile.am including gtk-doc.make) With --ignore-decorators="WEBKIT_API" and IGNORE_HFILES one can filter out / avoid most issues, I'm sure the same could be done even without autotools integration. Whether or not you use autotools I'd argue you should maintain the webkit-docs.sgml file yourself in order to set up any kind of reasonable structure.
On related note, to add overview documentation for the whole class you should add a template similar to the following in each relevant .cpp file: +/** + * SECTION:webkitwebview + * @short_description: Widget that displays a WebkitWebFrame + * @include: webkit/webkit.h + * + * Not written yet (OOPS!) + */ It's unclear for me how exactly the SECTION id is derived, I suppose it's the basename of the file.
Comment on attachment 19701 [details] Add gtk-doc build infrastructure. The patch is very good, but it is not working for srcdir != builddir. The documentation gets generated in the srcdir.
When you have gtk-doc working, please request that it be added to library.gnome.org (via the website product in bugzilla.gnome.org) and add a link to it from http://live.gnome.org/WebKitGtk
(In reply to comment #4) > (From update of attachment 19701 [details] [review]) > The patch is very good, but it is not working for srcdir != builddir. The > documentation gets generated in the srcdir. hehe, month passed and I recognize that srcdir != builddir is not possible with gtk-doc anyway? Why did no one point that out. :)
Created attachment 25386 [details] Fix existing API Documentation Fix the existing API Documentation. Fix references, naming of variables.
Created attachment 25387 [details] Add gtk-doc configuration files Add the required files for gtk-doc. This includes -docs.sgml, -sections.txt.
Created attachment 25388 [details] Fix existing API Documentation Fix existing API documentation. Naming of parameters, signal references.
Created attachment 25389 [details] Add gtk-doc configuration files The correct patch. -docs.sgml, -sections.txt
Created attachment 25390 [details] Integrate gtk-doc in the build process This looks awfully similar to the original patch. To build the documentation we require srcdir == builddir. This is true for any user of gtk-doc (pango and ...), we also need a recursive target as gtk-doc.make will not play nicely with our GNUmakefile.am. The good thing is that generating documentation is not enabled by default so we will not break anyones build. To generate the documentation --enable-gtk-doc needs to be passed.
Created attachment 25391 [details] WIP Add section information and examples Work In Progress. Add SECTION: and programlisting/examples to the documentation.
Comment on attachment 25389 [details] Add gtk-doc configuration files rs=me
Comment on attachment 25388 [details] Fix existing API Documentation Clearing review.
Comment on attachment 25389 [details] Add gtk-doc configuration files Clearing review too.
Comment on attachment 25390 [details] Integrate gtk-doc in the build process Hi Holger > +INCLUDES= \ > + -I$(top_srcdir)/WebKit/gtk \ > + -I$(top_builddir)/WebKit/gtk \ > + $(global_cppflags) \ > + $(global_cflags) \ > + -I$(top_srcdir) \ > + -I$(top_srcdir)/JavaScriptCore \ > + -I$(top_srcdir)/JavaScriptCore/ForwardingHeaders \ > + -I$(top_srcdir)/JavaScriptCore/parser \ > + -I$(top_srcdir)/JavaScriptCore/wtf \ > + -I$(top_builddir)/DerivedSources \ > + $(GLOBALDEPS_CFLAGS) \ > + $(CAIRO_CFLAGS) \ > + $(GTK_CFLAGS) Do we need all of the above? > diff --git a/WebKit/gtk/docs/version.xml.in b/WebKit/gtk/docs/version.xml.in > new file mode 100644 > index 0000000..d78bda9 > --- /dev/null > +++ b/WebKit/gtk/docs/version.xml.in > @@ -0,0 +1 @@ > +@VERSION@ Should we add version.xml.in to EXTRA_DIST? > diff --git a/WebKit/gtk/docs/webkitgtk-docs.sgml b/WebKit/gtk/docs/webkitgtk-docs.sgml > index 9b41ed6..2f50ce5 100644 > --- a/WebKit/gtk/docs/webkitgtk-docs.sgml > +++ b/WebKit/gtk/docs/webkitgtk-docs.sgml > @@ -1,14 +1,12 @@ > <?xml version="1.0"?> > <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" > - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> > + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ > +<!ENTITY version SYSTEM "version.xml"> > +]> > <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> > <bookinfo> > - <title>webkitgtk Reference Manual</title> > - <releaseinfo> > - for webkitgtk [VERSION] > - The latest version of this documentation can be found on-line at > - <ulink role="online-location" url="http://[SERVER]/webkitgtk/index.html">http://[SERVER]/webkitgtk/</ulink>. > - </releaseinfo> > + <title>WebKit/Gtk+ Reference Manual</title> > + <releaseinfo>for WebKit/Gtk+ &version;</releaseinfo> > </bookinfo> > > <chapter> > diff --git a/autogen.sh b/autogen.sh > index a929538..882eba9 100755 > --- a/autogen.sh > +++ b/autogen.sh > @@ -10,6 +10,14 @@ cd $srcdir > > DIE=0 > > +(gtkdocize --version) < /dev/null > /dev/null 2>&1 || { > + echo > + echo "You must have gtkdocize installed to compile $PROJECT." > + echo "Install the appropriate package for your distribution," > + echo "or get the source tarball at http://ftp.gnome.org/pub/GNOME/sources/gtk-doc/" > + DIE=1 > +} > + > (autoconf --version) < /dev/null > /dev/null 2>&1 || { > echo > echo "You must have autoconf installed to compile $PROJECT." > @@ -46,6 +54,7 @@ rm -rf $top_srcdir/autom4te.cache > > touch README INSTALL > > +gtkdocize || exit $? You might want to move this after LIBTOOLIZE below. > aclocal || exit $? > $LIBTOOLIZE --force || exit $? > autoheader || exit $? > diff --git a/configure.ac b/configure.ac > index f48f98f..c37d3ef 100644 > --- a/configure.ac > +++ b/configure.ac > @@ -670,6 +670,8 @@ if test "$enable_video" = "yes"; then > html_flags=yes > fi > > +GTK_DOC_CHECK([1.10]) Please move this at the top so we fail early if gtk-doc is not found but builder wants gtk-doc. > + > # OS conditionals > AM_CONDITIONAL([OS_WIN32],[test "$os_win32" = "yes"]) > AM_CONDITIONAL([OS_UNIX],[test "$os_win32" = "no"]) > @@ -718,6 +720,8 @@ AC_CONFIG_FILES([ > GNUmakefile > WebKit/gtk/webkit-1.0.pc:WebKit/gtk/webkit.pc.in > WebKit/gtk/webkit/webkitversion.h > +WebKit/gtk/docs/GNUmakefile > +WebKit/gtk/docs/version.xml Lastly, try to do the same as the pc file generation above (e.g. ...version.xml:WebKit/gtk/docs/versio.xml.in) Cheers,
Created attachment 25597 [details] Add Section Documentation and informal examples Add SECTION for our classes/objects, add some informal examples.
(In reply to comment #15) > index f48f98f..c37d3ef 100644 > --- a/configure.ac > +++ b/configure.ac > @@ -670,6 +670,8 @@ if test "$enable_video" = "yes"; then > html_flags=yes > fi > > +GTK_DOC_CHECK([1.10]) > + gtk-doc help suggest to add AC_CONFIG_MACRO_DIR(m4) too (see http://library.gnome.org/devel/gtk-doc-manual/stable/settingup_autoconf.html) > diff --git a/WebKit/gtk/docs/GNUmakefile.am b/WebKit/gtk/docs/GNUmakefile.am > new file mode 100644 I think you could remove general comment about macro usage, keeping only relevant info. Could also be useful add DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc As suggested http://library.gnome.org/devel/gtk-doc-manual/stable/settingup_automake.html About documentation itself, could be useful add an Overview section like: <chapter id="overview"> <title>WebKit/Gtk Overview</title> <para> WebKit/Gtk is the <ulink role="online-location" url="http://www.gtk.org">GTK+</ulink> port for <ulink role="online-location" url="http://www.webkit.org">WebKit</ulink>, the open source web browser engine. A port of WebKit is a unique combination of platform technologies that run the WebKit engine. WebKit/Gtk port uses the graphic tecnologies provided by GTK+ toolkit. </para> </chapter> this overview chapter could be extended with sub-sections related to building (dependencies, configure options..), compiling (against webkit, i.e. what pkg-config stuff you have to use in order to use webkitgtk in your project) and other stuff like the glib and gtk api refs overview (see [1] and [2]) Stupid final note: don't forget to add version control "ignore" property to files generated by gtk-doc, for example gtk-doc.make and all .html files. [1] http://library.gnome.org/devel/glib/stable/glib.html [2] http://library.gnome.org/devel/gtk/stable/gtk.html
Comment on attachment 25597 [details] Add Section Documentation and informal examples Looks fine, r=me.
Comment on attachment 25597 [details] Add Section Documentation and informal examples Landed in r39532 and clearing review.
Created attachment 28169 [details] doc structure updates required after the initial patch is landed, or should we merge? I'm not providing a changelog here, but I will of course add one when we land. I'm posting the patches here just so that they don't get forgotten in my local computer.
Created attachment 28170 [details] section docs for two new objects
(In reply to comment #22) > Created an attachment (id=28170) [review] > section docs for two new objects I think the adjective "asynchronous(ly)" should be mentioned in the section about the WebPolicyAction since that's the main reason why it exists.
Created attachment 28640 [details] changes I made to support 1.1.2 This is a fair amount of unrelated changes. I intend to split them when we have landed the initial bits, so that they make sense as changesets.
Created attachment 29082 [details] Updated gtk-doc configuration files for 1.1.4 WebKit/gtk/docs/webkitgtk-docs.sgml | 6 ++++++ WebKit/gtk/docs/webkitgtk-sections.txt | 9 +++++++++ 2 files changed, 15 insertions(+), 0 deletions(-)
Created attachment 29083 [details] Wrote a section about using the WEBKIT_DEBUG environment variable. WebKit/gtk/docs/GNUmakefile.am | 2 +- WebKit/gtk/docs/webkitenvironment.xml | 97 +++++++++++++++++++++++++++++++++ WebKit/gtk/docs/webkitgtk-docs.sgml | 5 ++ 3 files changed, 103 insertions(+), 1 deletions(-)
(In reply to comment #21) > Created an attachment (id=28169) [review] > doc structure updates required after the initial patch is landed, or should we > merge? > > I'm not providing a changelog here, but I will of course add one when we land. > I'm posting the patches here just so that they don't get forgotten in my local > computer. please merge it, I can review the merged result then.
Comment on attachment 29083 [details] Wrote a section about using the WEBKIT_DEBUG environment variable. > +<literal>--debug</literal> to the <literal>configure</literal> script. Isn't this --enable-debug?
Created attachment 29106 [details] integrate gtk-doc in the build process
Comment on attachment 28640 [details] changes I made to support 1.1.2 > + <xi:include href="xml/webkitsoupauthdialog.xml"/> Okay, we are not consistent here. Is WebKitSoupAuthDialog public API or not? I was under the assumption it is not. > - <title>Index of deprectaed symbols</title> > + <title>Index of deprecated symbols</title> make that a separate spelling fix commit. :)
Comment on attachment 29106 [details] integrate gtk-doc in the build process > + <title>WebKit/Gtk+ Reference Manual</title> > + <releaseinfo>for WebKit/Gtk+ &version;</releaseinfo> Use the right name and we need to get some help from Jan to integrate it in the make all target.
Comment on attachment 29106 [details] integrate gtk-doc in the build process Landed as r42123. Clearing the review flag.
Comment on attachment 28640 [details] changes I made to support 1.1.2 Okay, I got updated, WebKitSoupAuthDialog is supposed to be public API... Which means it deserves some padding in the class struct. :)
Comment on attachment 29083 [details] Wrote a section about using the WEBKIT_DEBUG environment variable. Landed as r42124, merged with attachment 28170 [details] and a piece of 28640, for better organization.
Comment on attachment 28170 [details] section docs for two new objects Landed as r42124, merged with attachment 29083 [details] and a piece of 28640, for better organization.
Landed as r42123, r42124, and r42125.