Skip to contentSkip to conversation

Add API documentation support

PATCH In review Thomas Wood 2 participants 3 messages Mar 11, 2014

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/2 Add API documentation support

Add optional support for building API documentation using gtk-doc.

---
 .gitignore                                         |   3 +
 Makefile.am                                        |   2 +-
 NEWS                                               |   2 +
 autogen.sh                                         |   7 ++
 configure.ac                                       |  12 +++
 docs/Makefile.am                                   |   1 +
 docs/reference/Makefile.am                         |   1 +
 docs/reference/intel-gpu-tools/.gitignore          |  26 +++++
 docs/reference/intel-gpu-tools/Makefile.am         | 105 +++++++++++++++++++++
 .../intel-gpu-tools/intel-gpu-tools-docs.xml       |  40 ++++++++
 docs/reference/intel-gpu-tools/version.xml.in      |   1 +
 11 files changed, 199 insertions(+), 1 deletion(-)
 create mode 100644 docs/Makefile.am
 create mode 100644 docs/reference/Makefile.am
 create mode 100644 docs/reference/intel-gpu-tools/.gitignore
 create mode 100644 docs/reference/intel-gpu-tools/Makefile.am
 create mode 100644 docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml
 create mode 100644 docs/reference/intel-gpu-tools/version.xml.in
.gitignore +3 -0
index 28ef75b..c622b7c 100644
@@ -83,3 +83,6 @@ TAGS
 build-aux/
 __pycache__
 version.h
+
+gtk-doc.make
+gtk-doc.m4
Makefile.am +1 -1
index 431e7b4..9949679 100644
@@ -21,7 +21,7 @@
 
 ACLOCAL_AMFLAGS = ${ACLOCAL_FLAGS} -I m4
 
-SUBDIRS = lib man tools scripts benchmarks demos overlay
+SUBDIRS = docs lib man tools scripts benchmarks demos overlay
 
 if BUILD_ASSEMBLER
 SUBDIRS += assembler
NEWS +2 -0
index 75352ae..22bb014 100644
@@ -26,6 +26,8 @@ Release 1.6 (2014-XX-YY)
 
 - Broadwell support for intel_audio_dump (Mengdong Lin).
 
+- API documentation support (Thomas)
+
 Release 1.5 (2013-11-06)
 ------------------------
 
autogen.sh +7 -0
index 354f254..629a257 100755
@@ -6,6 +6,13 @@ test -z "$srcdir" && srcdir=.
 ORIGDIR=`pwd`
 cd $srcdir
 
+if ! type gtkdocize > /dev/null 2>&1; then
+        echo "EXTRA_DIST =" > gtk-doc.make
+        echo "CLEANFILES =" >> gtk-doc.make
+else
+        gtkdocize || exit $?
+fi
+
 autoreconf -v --install || exit 1
 cd $ORIGDIR || exit $?
 
configure.ac +12 -0
index 4aee793..2c991a8 100644
@@ -42,6 +42,14 @@ AC_PROG_CC
 AM_PROG_LEX
 AC_PROG_YACC
 
+# check for gtk-doc
+m4_ifdef([GTK_DOC_CHECK], [
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+
+
 # Checks for functions, headers, structures, etc.
 AC_HEADER_STDC
 AC_CHECK_HEADERS([termios.h])
@@ -192,6 +200,10 @@ AC_CONFIG_FILES([
 		 Makefile
 		 benchmarks/Makefile
 		 demos/Makefile
+		 docs/Makefile
+		 docs/reference/Makefile
+		 docs/reference/intel-gpu-tools/Makefile
+		 docs/reference/intel-gpu-tools/version.xml
 		 lib/Makefile
 		 man/Makefile
 		 scripts/Makefile
docs/Makefile.am new file +1 -0
new file mode 100644
index 0000000..b68c774
@@ -0,0 +1 @@
+SUBDIRS=reference
docs/reference/Makefile.am new file +1 -0
new file mode 100644
index 0000000..4f579b5
@@ -0,0 +1 @@
+SUBDIRS = intel-gpu-tools
docs/reference/intel-gpu-tools/.gitignore new file +26 -0
new file mode 100644
index 0000000..9415974
@@ -0,0 +1,26 @@
+/gtkdoc-check.log
+/gtkdoc-check.trs
+/html-build.stamp
+/html.stamp
+/html/
+/intel-gpu-tools-decl-list.txt
+/intel-gpu-tools-decl.txt
+/intel-gpu-tools-overrides.txt
+/intel-gpu-tools-sections.txt
+/intel-gpu-tools-undeclared.txt
+/intel-gpu-tools-undocumented.txt
+/intel-gpu-tools-unused.txt
+/intel-gpu-tools.args
+/intel-gpu-tools.hierarchy
+/intel-gpu-tools.interfaces
+/intel-gpu-tools.prerequisites
+/intel-gpu-tools.signals
+/intel-gpu-tools.types
+/scan-build.stamp
+/setup-build.stamp
+/sgml-build.stamp
+/sgml.stamp
+/test-suite.log
+/version.xml
+/xml/
+
docs/reference/intel-gpu-tools/Makefile.am new file +105 -0

105 lines not on this page · raw message

docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml new file +40 -0
new file mode 100644
index 0000000..a3a66f5
@@ -0,0 +1,40 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>intel-gpu-tools Reference Manual</title>
+    <releaseinfo>
+      for intel-gpu-tools &version;.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>Intel GPU Tools</title>
+    <xi:include href="xml/debug.xml"/>
+    <xi:include href="xml/drmtest.xml"/>
+    <xi:include href="xml/igt_debugfs.xml"/>
+    <xi:include href="xml/igt_display.xml"/>
+    <xi:include href="xml/igt_kms.xml"/>
+    <xi:include href="xml/intel_batchbuffer.xml"/>
+    <xi:include href="xml/intel_chipset.xml"/>
+    <xi:include href="xml/intel_gpu_tools.xml"/>
+    <xi:include href="xml/media_fill.xml"/>
+    <xi:include href="xml/rendercopy.xml"/>
+
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
docs/reference/intel-gpu-tools/version.xml.in new file +1 -0
new file mode 100644
index 0000000..a24f987
@@ -0,0 +1 @@
+@PACKAGE_VERSION@
Signature · 1 line
1.8.5.3
#1 lore raw

PATCH 2/2 drmtest: reformat the API documentation

Make the existing documentation compatible with gtk-doc.

---
 lib/drmtest.c | 19 ++++++++---------
 lib/drmtest.h | 65 +++++++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 60 insertions(+), 24 deletions(-)
lib/drmtest.c +10 -9
index 9f6e701..20918b7 100644
@@ -176,9 +176,11 @@ void gem_quiescent_gpu(int fd)
 }
 
 /**
- * drm_get_card() - get an intel card number for use in /dev or /sys
+ * drm_get_card:
  *
- * returns -1 on error
+ * Get an intel card number for use in /dev or /sys
+ *
+ * Returns: -1 on error
  */
 int drm_get_card(void)
 {
@@ -1241,11 +1243,6 @@ bool __igt_fork_helper(struct igt_helper_process *proc)
 
 }
 
-/**
- * igt_waitchildren - wait for all children forked with igt_fork
- *
- * The magic here is that exit codes from children will be correctly propagated
- */
 void igt_stop_helper(struct igt_helper_process *proc)
 {
 	int status, ret;
@@ -1338,7 +1335,9 @@ bool __igt_fork(void)
 }
 
 /**
- * igt_waitchildren - wait for all children forked with igt_fork
+ * igt_waitchildren:
+ *
+ * Wait for all children forked with igt_fork
  *
  * The magic here is that exit codes from children will be correctly propagated
  */
@@ -1394,7 +1393,9 @@ bool igt_run_in_simulation(void)
 }
 
 /**
- * igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set
+ * igt_skip_on_simulation:
+ *
+ * Skip tests when INTEL_SIMULATION env war is set
  *
  * Skip the test when running on simulation (and that's relevant only when
  * we're not in the mode where we list the subtests).
lib/drmtest.h +50 -15

152 lines not on this page · raw message

Signature · 1 line
1.8.5.3
#2 lore raw

Re: [PATCH i-g-t 2/2] drmtest: reformat the API documentation

Quoted 3 lines · Thomas Wood

Make the existing documentation compatible with gtk-doc.

Both patches merged, with a little patch on top to pimp the configure output and README.

Thanks, Daniel

Quoted 231 lines
---
 lib/drmtest.c | 19 ++++++++---------
 lib/drmtest.h | 65 +++++++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 60 insertions(+), 24 deletions(-)
lib/drmtest.c +10 -9
index 9f6e701..20918b7 100644
@@ -176,9 +176,11 @@ void gem_quiescent_gpu(int fd)
 }
 
 /**
- * drm_get_card() - get an intel card number for use in /dev or /sys
+ * drm_get_card:
  *
- * returns -1 on error
+ * Get an intel card number for use in /dev or /sys
+ *
+ * Returns: -1 on error
  */
 int drm_get_card(void)
 {
@@ -1241,11 +1243,6 @@ bool __igt_fork_helper(struct igt_helper_process *proc)
 
 }
 
-/**
- * igt_waitchildren - wait for all children forked with igt_fork
- *
- * The magic here is that exit codes from children will be correctly propagated
- */
 void igt_stop_helper(struct igt_helper_process *proc)
 {
 	int status, ret;
@@ -1338,7 +1335,9 @@ bool __igt_fork(void)
 }
 
 /**
- * igt_waitchildren - wait for all children forked with igt_fork
+ * igt_waitchildren:
+ *
+ * Wait for all children forked with igt_fork
  *
  * The magic here is that exit codes from children will be correctly propagated
  */
@@ -1394,7 +1393,9 @@ bool igt_run_in_simulation(void)
 }
 
 /**
- * igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set
+ * igt_skip_on_simulation:
+ *
+ * Skip tests when INTEL_SIMULATION env war is set
  *
  * Skip the test when running on simulation (and that's relevant only when
  * we're not in the mode where we list the subtests).
lib/drmtest.h +50 -15
index b64529b..40510dc 100644
@@ -110,7 +110,11 @@ void igt_permute_array(void *array, unsigned size,
 						 unsigned j));
 void igt_progress(const char *header, uint64_t i, uint64_t total);
 
-/* init for simple tests without subtests */
+/**
+ * igt_simple_init:
+ *
+ * Init for simple tests without subtests
+ */
 void igt_simple_init(void);
 #define igt_simple_main \
 	static void igt_tokencat(__real_main, __LINE__)(void); \
@@ -133,7 +137,9 @@ int igt_subtest_init_parse_opts(int argc, char **argv,
 				igt_opt_handler_t opt_handler);
 bool __igt_run_subtest(const char *subtest_name);
 /**
- * igt_subtest/_f - Denote a subtest code block
+ * igt_subtest:
+ *
+ * Denote a subtest code block
  *
  * Magic control flow which denotes a subtest code block. Within that codeblock
  * igt_skip|success will only bail out of the subtest. The _f variant accepts a
@@ -148,6 +154,15 @@ bool __igt_run_subtest(const char *subtest_name);
 	     __igt_run_subtest( tmp ) && \
 	     (setjmp(igt_subtest_jmpbuf) == 0); \
 	     igt_success())
+
+/**
+ * igt_subtest_f:
+ * @...: format string
+ *
+ * Denote a subtest code block
+ *
+ * Like #igt_subtest, but also accepts a printf format string
+ */
 #define igt_subtest_f(f...) \
 	__igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f)
 #define igt_subtest(name) for (; __igt_run_subtest((name)) && \
@@ -165,27 +180,35 @@ const char *igt_subtest_name(void);
 
 
 /**
- * igt_skip - subtest aware test skipping
+ * igt_skip:
+ *
+ * Subtest aware test skipping
  *
  * For tests with subtests this will either bail out of the current subtest or
  * mark all subsequent subtests as SKIP (in case some global setup code failed).
  *
  * For normal tests without subtest it will directly exit.
  */
-__attribute__((format(printf, 1, 2))) void igt_skip(const char *f, ...) __attribute__((noreturn));
+__attribute__((format(printf, 1, 2)))
+void igt_skip(const char *f, ...) __attribute__((noreturn));
 __attribute__((format(printf, 5, 6)))
 void __igt_skip_check(const char *file, const int line,
 		      const char *func, const char *check,
 		      const char *format, ...) __attribute__((noreturn));
 /**
- * igt_success - complete a (subtest) as successfull
+ * igt_success:
+ *
+ * Complete a (subtest) as successfull
  *
  * This bails out of a subtests and marks it as successful. For global tests it
  * it won't bail out of anything.
  */
 void igt_success(void);
+
 /**
- * igt_fail - fail a testcase
+ * igt_fail:
+ *
+ * Fail a testcase
  *
  * For subtest it just bails out of the subtest, when run in global context it
  * will exit. Note that it won't attempt to keep on running further tests,
@@ -198,7 +221,9 @@ void __igt_fail_assert(int exitcode, const char *file,
 		       const char *format, ...)
 	__attribute__((noreturn));
 /**
- * igt_exit - exit() for igts
+ * igt_exit:
+ *
+ * exit() for igts
  *
  * This will exit the test with the right exit code when subtests have been
  * skipped. For normal tests it exits with a successful exit code, presuming
@@ -207,7 +232,9 @@ void __igt_fail_assert(int exitcode, const char *file,
  */
 void igt_exit(void) __attribute__((noreturn));
 /**
- * igt_assert - fails (sub-)test if a condition is not met
+ * igt_assert:
+ *
+ * Fails (sub-)test if a condition is not met
  *
  * Should be used everywhere where a test checks results.
  */
@@ -220,9 +247,9 @@ void igt_exit(void) __attribute__((noreturn));
 		__igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , f); \
 	} while (0)
 /**
- * igt_assert_cmptint
+ * igt_assert_cmptint:
  *
- * Like igt_assert(), but displays the values being compared on failure.
+ * Like #igt_assert, but displays the values being compared on failure.
  */
 #define igt_assert_cmpint(n1, cmp, n2) \
 	do { \
@@ -234,7 +261,9 @@ void igt_exit(void) __attribute__((noreturn));
 	} while (0)
 
 /**
- * igt_require - skip a (sub-)test if a condition is not met
+ * igt_require:
+ *
+ * Skip a (sub-)test if a condition is not met
  *
  * This is useful to streamline the skip logic since it allows for a more flat
  * code control flow.
@@ -254,8 +283,10 @@ bool __igt_fixture(void);
 void __igt_fixture_complete(void);
 void __igt_fixture_end(void) __attribute__((noreturn));
 /**
- * igt_fixture - annote global test fixture code
- * 
+ * igt_fixture:
+ *
+ * Annotate global test fixture code
+ *
  * Testcase with subtests often need to set up a bunch of global state as the
  * common test fixture. To avoid such code interferring with the subtest
  * enumeration (e.g. when enumerating on systemes without an intel gpu) such
@@ -270,10 +301,12 @@ void __igt_fixture_end(void) __attribute__((noreturn));
 
 bool __igt_fork(void);
 /**
- * igt_fork - fork parallel test threads with fork()
+ * igt_fork:
  * @child: name of the int variable with the child number
  * @num_children: number of children to fork
  *
+ * Fork parallel test threads with fork()
+ *
  * Joining all test threads should be done with igt_waitchildren to ensure that
  * the exit codes of all children are properly reflected in the test status.
  */
@@ -349,7 +382,9 @@ static inline void gem_require_ring(int fd, int ring_id)
 bool igt_run_in_simulation(void);
 #define SLOW_QUICK(slow,quick) (igt_run_in_simulation() ? (quick) : (slow))
 /**
- * igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set
+ * igt_skip_on_simulation:
+ *
+ * Skip tests when INTEL_SIMULATION env war is set
  *
  * Skip the test when running on simulation (and that's relevant only when
  * we're not in the mode where we list the subtests).
Signature · 6 lines
1.8.5.3

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch