Adding doxygen setup and info for the testing framework.

Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

.gitignore

@@ -29,6 +29,8 @@ cscope.out
 /config.sub
 /configure
 /depcomp
+/docs/developer
+/docs/tools
 /install-sh
 /libtool
 /ltmain.sh

Makefile.am

@@ -1058,6 +1058,7 @@ WESTON_LOG_COMPILER = $(srcdir)/tests/weston-tests-env
 
 clean-local:
 	-rm -rf logs
+	-rm -rf $(DOCDIRS)
 
 # To remove when automake 1.11 support is dropped
 export abs_builddir
@@ -1352,6 +1353,27 @@ EXTRA_DIST +=					\
 
 CLEANFILES += $(man_MANS)
 
+if ENABLE_DEVDOCS
+DOXYGEN_INDICES = docs/developer/html/index.html docs/tools/html/index.html
+
+docs/developer/html/index.html: doc/doxygen/tooldev.doxygen | docs/developer
+	cd doc/doxygen && $(DOXYGEN) tooldev.doxygen
+
+docs/tools/html/index.html: doc/doxygen/tools.doxygen | docs/tools
+	cd doc/doxygen && $(DOXYGEN) tools.doxygen
+endif
+
+DOCDIRS =		\
+	docs/developer	\
+	docs/tools
+
+$(DOCDIRS):
+	$(MKDIR_P) $@
+
+.PHONY: doc $(DOXYGEN_INDICES)
+
+doc: $(DOXYGEN_INDICES)
+
 protocol/%-protocol.c : $(top_srcdir)/protocol/%.xml
 	$(AM_V_GEN)$(MKDIR_P) $(dir $@) && $(wayland_scanner) code < $< > $@
 

README

@@ -18,6 +18,12 @@ weston and its dependencies.
 The test suite can be invoked via `make check`; see
 http://wayland.freedesktop.org/testing.html for additional details.
 
+Developer documentation can be built via `make doc`. Output will be in
+the build root under
+
+docs/developer/html/index.html
+docs/tools/html/index.html
+
 
 
 			Libweston

configure.ac

@@ -61,6 +61,25 @@ AC_CHECK_FUNCS([mkostemp strchrnul initgroups posix_fallocate])
 
 COMPOSITOR_MODULES="wayland-server >= 1.8.0 pixman-1 >= 0.25.2"
 
+AC_CONFIG_FILES([doc/doxygen/tools.doxygen doc/doxygen/tooldev.doxygen])
+
+AC_ARG_ENABLE(devdocs,
+	      AS_HELP_STRING([--disable-devdocs],
+			     [do not enable building of developer documentation]),,
+	      enable_devdocs=auto)
+if test "x$enable_devdocs" != "xno"; then
+	AC_CHECK_PROGS([DOXYGEN], [doxygen])
+	if test "x$DOXYGEN" = "x" -a "x$enable_devdocs" = "xyes"; then
+		AC_MSG_ERROR([Developer documentation explicitly requested, but Doxygen couldn't be found])
+	fi
+	if test "x$DOXYGEN" != "x"; then
+		enable_devdocs=yes
+	else
+		enable_devdocs=no
+	fi
+fi
+AM_CONDITIONAL(ENABLE_DEVDOCS, test "x$enable_devdocs" = "xyes")
+
 AC_ARG_ENABLE(egl, [  --disable-egl],,
               enable_egl=yes)
 AM_CONDITIONAL(ENABLE_EGL, test x$enable_egl = xyes)
@@ -549,6 +568,7 @@ AC_MSG_RESULT([
 
 	Build wcap utility		${enable_wcap_tools}
 	Build Fullscreen Shell		${enable_fullscreen_shell}
+	Enable developer documentation	${enable_devdocs}
 
 	weston-launch utility		${enable_weston_launch}
 	systemd-login support		${have_systemd_login}

doc/doxygen/devtools.dox

+/*
+ * Copyright © 2015 Samsung Electronics Co., Ltd
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the
+ * next paragraph) shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+@mainpage
+
+- @ref zunitc - Simple test framework
+
+@section tools_overview Overview
+
+The tools area currently consists of one sub-project (@ref zunitc) that is
+refined from the prior single weston/tests source folder.
+
+@subsection tools_overview_old Old Code Organization
+
+The original 'tests' folder contained basic weston testing with an
+integrated test runner framework. Over time things progressed to the
+stage where splitting apart into discrete layers was warranted.
+
+@dotfile tools_arch_old.gv "Original test code organization"
+
+@subsection tools_overview_new New Code Organization
+
+The test code that is not weston-specific gets split out to a separate
+folder and/or folders.
+
+@dotfile tools_arch_new.gv "Refactored test code organization"
+
+*/

doc/doxygen/tooldev.doxygen.in

+PROJECT_NAME           = "Tool Internals"
+OUTPUT_DIRECTORY       = @top_builddir@/docs/developer
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+EXTRACT_ALL            = YES
+INPUT                  = \
+		       @top_srcdir@/doc/doxygen/devtools.dox \
+		       @top_srcdir@/tools/zunitc
+RECURSIVE              = YES
+GENERATE_LATEX         = NO
+DOTFILE_DIRS           = @top_srcdir@/doc/doxygen

doc/doxygen/tools.dox

+/*
+ * Copyright © 2015 Samsung Electronics Co., Ltd
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the
+ * next paragraph) shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+@mainpage
+
+- @ref zunitc - Simple test framework
+
+*/

doc/doxygen/tools.doxygen.in

+PROJECT_NAME           = "Tools"
+OUTPUT_DIRECTORY       = @top_builddir@/docs/tools
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+INPUT                  = \
+		       @top_srcdir@/doc/doxygen/tools.dox \
+		       @top_srcdir@/tools/zunitc/doc/zunitc.dox \
+		       @top_srcdir@/tools/zunitc/inc/zunitc/zunitc.h
+GENERATE_LATEX         = NO
+DOTFILE_DIRS           = @top_srcdir@/doc/doxygen

doc/doxygen/tools_arch_new.gv

+/*
+ * Copyright © 2015 Samsung Electronics Co., Ltd
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the
+ * next paragraph) shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+digraph toolarch_new {
+    rankdir = "TB";
+
+    node[shape=record]
+
+    subgraph cluster_0 {
+        label = "./tests";
+
+        keyboard_test_c [label = "{keyboard-test.c|tests\l}"]
+        text_test_c [label = "{text-test.c|tests\l}"]
+        vertex_clip_test_c [label = "{vertex-clip-test.c|tests\l}"]
+
+	spacer [shape = point, style = invis]
+
+        weston_test_client_helper [label = "{weston-test-client-helper.h/.c|Weston test protocol\l}"]
+
+        weston_test_c [label = "{weston-test.c|Extension protocol\nimplementation}"]
+    }
+
+    subgraph cluster_1 {
+        label = "./tools/waycheck";
+
+	waycheck [label = "{waycheck.c| \n \n }"]
+    }
+
+    subgraph cluster_2 {
+        label = "./tools/wayland_fixtures";
+
+	wtst_fixtures [label = "{wtst_fixtures.h/c|Wayland tracking structs\lWayland callbacks\l}"]
+    }
+
+    subgraph cluster_3 {
+        label = "./tools/zunitc";
+
+	zunitc [label = "{zunitc|Test definition macros\lTest running functions\lTest reporting functions\lTest run lifecycle\l}"]
+    }
+
+    keyboard_test_c -> weston_test_client_helper
+    keyboard_test_c -> wtst_fixtures
+    keyboard_test_c -> zunitc
+    vertex_clip_test_c -> zunitc
+    text_test_c -> weston_test_client_helper
+    text_test_c -> wtst_fixtures
+    text_test_c -> zunitc
+
+    waycheck -> wtst_fixtures
+    waycheck -> zunitc
+
+    wtst_fixtures -> zunitc
+
+    edge [style = dashed, arrowhead = open]
+    weston_test_client_helper -> weston_test_c
+
+    edge [style = invis]
+    weston_test_client_helper -> zunitc
+
+    text_test_c -> spacer
+    keyboard_test_c -> spacer
+    spacer -> weston_test_client_helper
+}

doc/doxygen/tools_arch_old.gv

+/*
+ * Copyright © 2015 Samsung Electronics Co., Ltd
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the
+ * next paragraph) shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+digraph toolarch_old {
+    rankdir = "TB";
+
+    node[shape = record]
+
+    subgraph cluster_0 {
+        label = "./tests";
+
+        keyboard_test_c [label = "{keyboard-test.c|tests\l}"]
+        text_test_c [label = "{text-test.c|tests\l}"]
+        vertex_clip_test_c [label = "{vertex-clip-test.c|tests\l}"]
+
+        weston_test_client_helper [label = "{weston-test-client-helper.h/.c|Wayland tracking structs\lWeston test protocol\lWayland callbacks\lTest run lifecycle\l}"]
+
+        weston_test_c [label = "{weston-test.c|Extension protocol\nimplementation}"]
+        weston_test_runner [label = "{weston-test-runner.h/.c|Test definition macros\lTest running functions\lTest reporting functions\lTest run lifecycle\l}"]
+    }
+
+    weston_test_client_helper -> weston_test_runner
+    keyboard_test_c -> weston_test_client_helper
+    keyboard_test_c -> weston_test_runner
+    vertex_clip_test_c -> weston_test_runner
+    text_test_c -> weston_test_client_helper
+    text_test_c -> weston_test_runner
+
+    edge [style = dashed, arrowhead = open]
+    weston_test_client_helper -> weston_test_c
+}