After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 165963 - accept section docs from the sources as well
accept section docs from the sources as well
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
: 142647 (view as bug list)
Depends on:
Blocks:
 
 
Reported: 2005-02-01 19:33 UTC by Stefan Sauer (gstreamer, gtkdoc dev)
Modified: 2006-04-15 11:47 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
first implementation (2.67 KB, patch)
2005-02-01 19:59 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
none Details | Review

Description Stefan Sauer (gstreamer, gtkdoc dev) 2005-02-01 19:33:58 UTC
The ideas as discussed on the mailinglist is to acces docs like
/**
 * SECTION:btsong
 * @summary: short desc
 * @see: other classes
 * @title: Song class
 *
 * Long desc
 */

I just wonder wheter it would we should use @summary and @see or
@short_description and @see_also (to use the equivalent of the sqml templates)
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2005-02-01 19:59:57 UTC
Created attachment 36837 [details] [review]
first implementation

patch is against gnome-cvs sources
Comment 2 Damon Chaplin 2005-02-01 23:37:39 UTC
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.
Comment 3 Damon Chaplin 2005-02-05 12:40:06 UTC
*** Bug 142647 has been marked as a duplicate of this bug. ***
Comment 4 James Bowes 2005-03-25 23:07:57 UTC
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.
Comment 5 Damon Chaplin 2005-03-26 11:19:17 UTC
I changed it to allow whitespace after SECTION: a few weeks back, so that will
be in the next release.
Comment 6 James Bowes 2005-03-26 14:13:54 UTC
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
Comment 7 Damon Chaplin 2005-07-26 21:00:11 UTC
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.
Comment 8 Stefan Sauer (gstreamer, gtkdoc dev) 2005-07-27 07:14:36 UTC
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 ...
Comment 9 Damon Chaplin 2005-07-27 10:08:14 UTC
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.
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2005-07-27 10:57:07 UTC
doh, forgot the set the _GLOB for a subproject. Anyway adding the $(HFILE_GLOB)
to the sgml-build.stamp: target sounds reasonable to me.
Comment 11 Stefan Sauer (gstreamer, gtkdoc dev) 2005-07-29 08:03:44 UTC
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 ;)
Comment 12 Damon Chaplin 2005-07-29 10:05:39 UTC
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.
Comment 13 Stefan Sauer (gstreamer, gtkdoc dev) 2005-07-29 11:29:23 UTC
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?
Comment 14 Owen Taylor 2005-07-29 11:44:58 UTC
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. 
Comment 15 Stefan Sauer (gstreamer, gtkdoc dev) 2006-03-21 13:13:49 UTC
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?
Comment 16 Damon Chaplin 2006-03-26 12:02:08 UTC
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.
Comment 17 Damon Chaplin 2006-04-15 11:47:43 UTC
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.