GNOME.org
 

Re: How to create docs for signal prototypes

Damon & Others:

> > gtk-doc Experts:
> > 
> > I am writing my own GObjects that define their own signals.
> > How do I get the Signal Handler Prototypes for these signals
> > to appear in my generated gtk-docs?
> 
> They should appear in the docs. (See the GTK+ docs on developer.gnome.org
> if you don't believe me!)
>
> You have to set up the Makefiles so that they run gtkdoc-scangobj
> to dynamically grab information about the signals. gtk-doc in CVS has
> example Makefiles for this. Also see the GTK+ Makefiles.

I'm looking a little deeper into the situation, and I notice that
the Makefile that I'm using in my docs directory is calling
the gtkdoc-scangobj script.

However I am still not seeing the signals show up in the generated docs.

Maybe an example would help.  I'm specifically talking about the ATK
code.  The interface that defines two signals is AtkTable.  If you look
at it you can see it defines a ROW_INSERTED, ROW_DELETED, COLUMN_INSERTED,
COLUMN_DELETED, ROW_REORDERED, and COLUMN_REORDERED signals:

http://cvs.gnome.org/bonsai/cvsblame.cgi?file=atk/atk/atktable.c&rev=&root=/cvs/gnome

The signals are initialized in the atk_table_base_init funciton which starts on
line #66 of this file.  I should mention that AtkTable is an interface, so
perhaps I need to define my signals differently to get them to show up in
the docs?  Or perhaps signals defined for interfaces aren't intended to show
up in the docs? 

I was digging through the GTK+ code and couldn't really find any good examples of
interfaces that define signals.  In our situation we want all people who implement
the interface to be required to implement the two signals, so it seems to make
sense to define them in the interface itself.  But it would also be nice if
users could look at the docs to see that the signals are defined, what arguments
they pass, etc.

If you look at the Makefile.am in the atk/docs directory.  On line 56 you can
see that we are calling gtkdoc-scangobj here:

http://cvs.gnome.org/bonsai/cvsblame.cgi?file=atk/docs/Makefile.am&rev=&root=/cvs/gnome

I've also attached the generated atk/docs/Makefile if you find that
easier to read.

I would appreciate any input.  Thanks!

Brian

# Generated automatically from Makefile.in by configure.
# Makefile.in generated automatically by automake 1.4-p1 from Makefile.am

# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.


SHELL = /sgnome/gnome1.4/sparc-solaris/bin/bash

srcdir = .
top_srcdir = ..
prefix = /opt/gnome-2.0
exec_prefix = ${prefix}

bindir = ${exec_prefix}/bin
sbindir = ${exec_prefix}/sbin
libexecdir = ${exec_prefix}/libexec
datadir = ${prefix}/share
sysconfdir = ${prefix}/etc
sharedstatedir = ${prefix}/com
localstatedir = ${prefix}/var
libdir = ${exec_prefix}/lib
infodir = ${prefix}/info
mandir = ${prefix}/man
includedir = ${prefix}/include
oldincludedir = /usr/include

DESTDIR =

pkgdatadir = $(datadir)/atk
pkglibdir = $(libdir)/atk
pkgincludedir = $(includedir)/atk

top_builddir = ..

ACLOCAL = aclocal
AUTOCONF = autoconf
AUTOMAKE = automake
AUTOHEADER = autoheader

INSTALL = /sgnome/gnome2.0/sparc-solaris/bin/install -c
INSTALL_PROGRAM = ${INSTALL} $(AM_INSTALL_PROGRAM_FLAGS)
INSTALL_DATA = ${INSTALL} -m 644
INSTALL_SCRIPT = ${INSTALL_PROGRAM}
transform = s,x,x,

NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
host_alias = sparc-sun-solaris2.9
host_triplet = sparc-sun-solaris2.9
AS = @AS@
ATK_MAJOR_VERSION = 0
ATK_MICRO_VERSION = 2
ATK_MINOR_VERSION = 0
ATK_VERSION = 0.2
AWK = gawk
CC = gcc
DLLTOOL = @DLLTOOL@
ECHO = echo
EXEEXT = 
GLIB_CFLAGS =  -I/opt/gnome-2.0/include/glib-2.0 -I/opt/gnome-2.0/lib/glib-2.0/include  
GLIB_GENMARSHAL = glib-genmarshal
GLIB_LIBS =  -L/opt/gnome-2.0/lib -lglib-1.3 -liconv  
GLIB_MKENUMS = glib-mkenums
GLIB_PACKAGES = gobject-2.0 gmodule-2.0
GOBJECT_QUERY = gobject-query
GTKDOC = true
LIBTOOL = $(SHELL) $(top_builddir)/libtool
LN_S = ln -s
LT_AGE = 0
LT_CURRENT = 2
LT_RELEASE = 0.0
LT_REVISION = 0
MAKEINFO = makeinfo
OBJDUMP = @OBJDUMP@
OBJEXT = o
PACKAGE = atk
PANGO_PACKAGES = pango
PERL = perl5
PKG_CONFIG = /opt/gnome-2.0/bin/pkg-config
RANLIB = ranlib
REBUILD = 
STRIP = strip
VERSION = 0.2

EXTRA_DIST =  	$(content_files)			$(extra_files)				$(HTML_IMAGES)				$(DOC_MAIN_SGML_FILE)			$(DOC_MODULE)-sections.txt		$(DOC_MODULE)-overrides.txt


# The name of the module.
DOC_MODULE = atk

# The top-level SGML file.
DOC_MAIN_SGML_FILE = atk-docs.sgml

# The directory containing the source code (if it contains documentation).
DOC_SOURCE_DIR = ../atk

INSTALLDIR = $(prefix)/share/gtk-doc

HTML_DIR = ${datadir}/gtk-doc/html

####################################
# Everything below here is generic #
####################################

TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)

# Images to copy into HTML directory
HTML_IMAGES = 

# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
content_files = 

# Other files to distribute
extra_files = 

DOC_STAMPS = scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \	   $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp

SCANOBJ_FILES =  	$(DOC_MODULE).args		$(DOC_MODULE).hierarchy 	$(DOC_MODULE).signals

mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
CONFIG_CLEAN_FILES = 
DIST_COMMON =  Makefile.am Makefile.in


DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)

TAR = gtar
GZIP_ENV = --best
all: all-redirect
.SUFFIXES:
$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) 
	cd $(top_srcdir) && $(AUTOMAKE) --gnu docs/Makefile

Makefile: $(srcdir)/Makefile.in  $(top_builddir)/config.status $(BUILT_SOURCES)
	cd $(top_builddir) \
	  && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status

tags: TAGS
TAGS:


distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)

subdir = docs

distdir: $(DISTFILES)
	here=`cd $(top_builddir) && pwd`; \
	top_distdir=`cd $(top_distdir) && pwd`; \
	distdir=`cd $(distdir) && pwd`; \
	cd $(top_srcdir) \
	  && $(AUTOMAKE) --include-deps --build-dir=$$here --srcdir-name=$(top_srcdir) --output-dir=$$top_distdir --gnu docs/Makefile
	@for file in $(DISTFILES); do \
	  d=$(srcdir); \
	  if test -d $$d/$$file; then \
	    cp -pr $$d/$$file $(distdir)/$$file; \
	  else \
	    test -f $(distdir)/$$file \
	    || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
	    || cp -p $$d/$$file $(distdir)/$$file || :; \
	  fi; \
	done
	$(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-hook
info-am:
info: info-am
dvi-am:
dvi: dvi-am
check-am: all-am
check: check-am
installcheck-am:
installcheck: installcheck-am
install-exec-am:
install-exec: install-exec-am

install-data-am: install-data-local
install-data: install-data-am

install-am: all-am
	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
install: install-am
uninstall-am:
uninstall: uninstall-am
all-am: Makefile all-local
all-redirect: all-am
install-strip:
	$(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install
installdirs:


mostlyclean-generic:

clean-generic:

distclean-generic:
	-rm -f Makefile $(CONFIG_CLEAN_FILES)
	-rm -f config.cache config.log stamp-h stamp-h[0-9]*

maintainer-clean-generic:
mostlyclean-am:  mostlyclean-generic

mostlyclean: mostlyclean-am

clean-am:  clean-generic mostlyclean-am clean-local

clean: clean-am

distclean-am:  distclean-generic clean-am
	-rm -f libtool

distclean: distclean-am

maintainer-clean-am:  maintainer-clean-generic distclean-am \
		maintainer-clean-local
	@echo "This command is intended for maintainers to use;"
	@echo "it deletes files that may require special tools to rebuild."

maintainer-clean: maintainer-clean-am

.PHONY: tags distdir info-am info dvi-am dvi check check-am \
installcheck-am installcheck install-exec-am install-exec \
install-data-local install-data-am install-data install-am install \
uninstall-am uninstall all-local all-redirect all-am all installdirs \
mostlyclean-generic distclean-generic clean-generic \
maintainer-clean-generic clean mostlyclean distclean maintainer-clean


all-local: html-build.stamp

#### scan ####

scan-build.stamp: $(HFILE_GLOB)
	@echo '*** Scanning header files ***'
	if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null ; then \
	    CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \
		else \
	cd $(srcdir) ; \
	for i in $(SCANOBJ_FILES) ; do \
		test -f $$i || touch $$i ; \
	done \
        fi
	cd $(srcdir) && \
	  gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
	touch scan-build.stamp

$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp
	@true

#### templates ####

tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
	@echo '*** Rebuilding template files ***'
	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
	touch tmpl-build.stamp

tmpl.stamp: tmpl-build.stamp
	@true

#### sgml ####

sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
	@echo '*** Building SGML ***'
	cd $(srcdir) && \
        gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
	touch sgml-build.stamp

sgml.stamp: sgml-build.stamp
	@true

#### html ####

html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
	@echo '*** Building HTML ***'
	test -d $(srcdir)/html || mkdir $(srcdir)/html
	cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
	test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
	@echo '-- Fixing Crossreferences'
	cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
	touch html-build.stamp

##############

clean-local:
	rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)

maintainer-clean-local: clean
	cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt

install-data-local:
	$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
	(installfiles=`echo $(srcdir)/html/*.html`; \
	if test "$$installfiles" = '$(srcdir)/html/*.html'; \
	then echo '-- Nothing to install' ; \
	else \
	  for i in $$installfiles; do \
	echo '-- Installing '$$i ; \
	$(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \
	  done; \
	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
	fi)

#
# Require gtk-doc when making dist
#
dist-check-gtkdoc:
#dist-check-gtkdoc:
#	@echo "*** gtk-doc must be installed and enabled in order to make dist"
#	@false

dist-hook: dist-check-gtkdoc dist-hook-local
	mkdir $(distdir)/tmpl
	mkdir $(distdir)/sgml
	mkdir $(distdir)/html
	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
	cp $(srcdir)/html/index.sgml $(distdir)/html
	-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html

	images=$(HTML_IMAGES) ;			\
	for i in $$images ; do			\
	  cp $(srcdir)/$$i $(distdir)/html ;  \
	done

.PHONY : html sgml templates scan dist-hook-local

# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]