Temporary: play with documentation of examples

doc/Doxyfile.in

@@ -856,7 +856,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @top_srcdir@/src \
-                         @top_srcdir@/doc/mainpage.dox
+                         @top_srcdir@/doc/mainpage.dox \
+                         @top_srcdir@/doc/examples.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -934,7 +935,7 @@ EXCLUDE_SYMBOLS        = SC_EXTERN_C_BEGIN \
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = @top_srcdir@/example/steps
+EXAMPLE_PATH           = @top_srcdir@/example/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

doc/examples.dox

@@ -0,0 +1,49 @@
+/*
+  This file is part of p4est.
+  p4est is a C library to manage a collection (a forest) of multiple
+  connected adaptive quadtrees or octrees in parallel.
+
+  Copyright (C) 2010 The University of Texas System
+  Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
+
+  p4est is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  p4est is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with p4est; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \page Examples
+ * Documentation page for example programs.
+ *
+ * One nice example is this one: \ref steps/p4est_step1.c.
+ * It does this and that.
+ *
+ * Another nice example is this one: \ref steps/p4est_step2.c
+ * It does something else.
+ *
+ * Second paragraph.
+ */
+
+/** \example simple/simple2.c
+ *
+ * Document example simple here in this text block.
+ */
+
+/** \example steps/p4est_step1.c
+ *
+ * Document the first step example in this text block.
+ */
+
+/** \example steps/p4est_step2.c
+ *
+ * Document the second step example in this text block.
+ */

example/steps/p4est_step1.c

@@ -22,8 +22,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \file p4est_step1.c
- *
+/*
  * This 2D example program refines a domain based on given image data.
  * The image file hw32.h has been created with the GIMP and is compiled in.
  */
@@ -39,17 +38,17 @@
 #endif
 #include "hw32.h"
 
-/** The resolution of the image data in powers of two. */
+/* The resolution of the image data in powers of two. */
 #define P4EST_STEP1_PATTERN_LEVEL 5
-/** The dimension of the image data. */
+/* The dimension of the image data. */
 #define P4EST_STEP1_PATTERN_LENGTH (1 << P4EST_STEP1_PATTERN_LEVEL)
-static const int    plv = P4EST_STEP1_PATTERN_LEVEL;    /**< Shortcut */
-static const int    ple = P4EST_STEP1_PATTERN_LENGTH;   /**< Shortcut */
+static const int    plv = P4EST_STEP1_PATTERN_LEVEL;    /*< Shortcut */
+static const int    ple = P4EST_STEP1_PATTERN_LENGTH;   /*< Shortcut */
 #ifdef P4_TO_P8
 static const p4est_qcoord_t eighth = P4EST_QUADRANT_LEN (3);
 #endif
 
-/** Callback function to decide on refinement.
+/* Callback function to decide on refinement.
  *
  * Refinement and coarsening is controlled by callback functions.
  * This function is called for every processor-local quadrant in order; its
@@ -110,7 +109,7 @@ refine_fn (p4est_t * p4est, p4est_topidx_t which_tree,
   return 0;
 }
 
-/** The main function of the step1 example program.
+/* The main function of the step1 example program.
  *
  * It creates a connectivity and forest, refines it, and writes a VTK file.
  */