Created attachment 36837 [details] [review]
first implementation

patch is against gnome-cvs sources

A simple patch for a change. Phew!

I've committed it as it doesn't seem to break anything.
I also changed it to use @short_description and @see_also (in upper or lower case).


I've just committed Brian's patch for stability levels, so we also need to
support @stability: here as well.

We also need to update the docs, and it would be useful to update the
tools/gtk-doc.el emacs lisp code to support adding the section docs.
So I'll leave this bug open for a bit.

*** Bug 142647 has been marked as a duplicate of this bug. ***

Currently, there can't be any whitespace between SECTION: and the section name.
i.e. SECTION:foo 
is valid, but 
SECTION: foo
is not.

It would be nice to be able to have whitespace there. This has to do with the
regex that grabs $symbol. I'm not sure how to fix it myself, though; my regex
skills aren't the best.

I changed it to allow whitespace after SECTION: a few weeks back, so that will
be in the next release.

I think the problem still exists with the regex for getting $symbol
(on line 2521 of gtkdoc-mkdb.in), rather than in getting $real_symbol out of
$symbol (line 2461).

For example:

gtk-doc $ echo "SECTION: foo" | perl -ne 'if (m%^\s*([\w:-]*\w)\s*:?%){print
"$1\n";}'
SECTION

gtk-doc $ echo "SECTION:foo" | perl -ne 'if (m%^\s*([\w:-]*\w)\s*:?%){print
"$1\n";}'
SECTION:foo

I see. You mean this part:

	# If we haven't found the symbol name yet, look for it.
	if (!$symbol) {
	    if (m%^\s*([\w:-]*\w)\s*:?%) {
		$symbol = $1;
	    }
	    next;
	}

That regex is a bit messy. We need to match normal C symbols,
object:property, object::signal, and SECTION:\s*foo. All can end in
an optional ':'.

I think the easiest thing is to just add an extra regex:
            if (m%^\s*(SECTION:\s*\w+)%) {
                $symbol = $1;
	    } elsif (m%^\s*([\w:-]*\w)\s*:?%) {
		$symbol = $1;
	    }

I need to test this before committing.

After I changed our project to only use inline section docs, I notices that the
dependency tracking of gtk-doc might need adjustment. Right now even though I
have the files under tmpl/ I don't touch them. But after a chages in the
sources, docs don't get rebuilt (requires removing the *.stamp) files.
I'll try to look into it soon ...

We do have a dependency on $(CFILE_GLOB) for building the XML:

sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
$(expand_content_files)

Is your $(CFILE_GLOB) set correctly in the Makefile.am?
e.g. for GTK+ it is (in gtk+/docs/reference/gtk/Makefile.am):
  CFILE_GLOB=$(top_srcdir)/gtk/*.c

Actually I think we should have an $(HFILE_GLOB) as a dependency as well,
since docs can be placed in header files.

doh, forgot the set the _GLOB for a subproject. Anyway adding the $(HFILE_GLOB)
to the sgml-build.stamp: target sounds reasonable to me.

No I get this during make:
*** Rebuilding template files ***
cd . && gtkdoc-mktmpl --module=bt-core
   ... snip ...
touch tmpl-build.stamp
make[4]: *** No rule to make target `tmpl/*.sgml', needed by `sgml-build.stamp'.
 Stop.

I needed to change the rule in the makefile from:
  sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
to
  sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(HFILE_GLOB)

I don't know wheter we should change this is CVS. Probably when the
--no-tmpl-files mode works and we have docs that don't mention that these files
have ever exist ;)

I don't quite understand. Did you delete tmpl/* and then try to build the docs?
We don't support that yet. I would like to, but it probably needs lots of changes.

All I did is to remove the tmpl files from CVS. That is I just rebuild them, but
all doc changes happen only in sources (*.{c,h}). gtk-doc builds the *.sgml
files in the tmpl dir fine, but somehow the rule
sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
belives it has not and tries to find a rule to build the 'missing' dependency
$(srcdir)/tmpl/*.sgml

I really don't understand whats going on. Apparently it not happens for you, right?

It's a consequence of how globs work in Make ... you'd have to redo the
rules not to depend on the glob for it to work with those files being
generated. 

I see two ways to fix it:
1.) have a file called temp/.dummy.sgml (which is part of CVS).
this is ugly IMHO

2.) when generating the tmpl/*.sgml file check if dir is empty and if so, restart make afterwards ($(MAKE) -C .)

Any better idea?

I think using temp/.dummy.sgml is fine for now.

The real solution is to get gtk-doc to work without tmpl files.

We'd need:

 1) a separate set of make rules in gtk-doc.make that the developer can
    switch on somehow.
    (Actually it might be enough just to make tmpl.stamp depend on
    $(DOC_MODULE)-decl.txt, so the gtkdoc-mktmpl step is just skipped.
    We could also pass a "--no-templates" option to gtkdoc-mkdb so it doesn't
    output warnings about missing template files.)

 2) gtkdoc-mkdb needs updating to work without the template files.
    Currently I think it needs them for ordering function arguments, but
    we could just use the order from the source code if the templates aren't
    there.

I don't think it is that difficult to do. A couple of hours, I think.

I think we can close this now. I just committed the change allowing whitespace
after "SECTION:" (a bit late, I know). I also added a C-x4s keybinding to add
an empty section header in tools/gtk-doc.el.

bug 338068 covers the template-free build issue, which I think is the last
remaining issue.