Initial revisionHEADoriginmaster

18 files changed, 295 insertions, 0 deletions

diff --git a/eg/boxcomment.c b/eg/boxcomment.c
new file mode 100644
index 0000000..f5f0379
--- /dev/null
+++ b/eg/boxcomment.c
@@ -0,0 +1,41 @@
+/***************************************************************************
+ * C style box comment.
+ *
+ * This function has a very pretty C style box comment.
+ ***************************************************************************/
+void boxcomm_c1(void);
+
+/***************************************************************************
+/ Fancier C style box comment.
+/
+/ This function has a very pretty C style box comment.
+/***************************************************************************/
+void boxcomm_c2(void);
+
+/***************************************************************************
+/*** Even Fancier C style box comment.
+/***
+/*** This function has a very pretty C style box comment.
+/***************************************************************************/
+void boxcomm_c3(void);
+
+/*-------------------------------------------------------------------------
+ * C style box comment.
+ *
+ * This function has a dashed C style box comment.
+ *-------------------------------------------------------------------------*/
+void boxcomm_c4(void);
+
+////////////////////////////////////////////////////////////////////////////
+// C++ style box comment.
+//
+// This function has a very pretty C++ style box comment.
+////////////////////////////////////////////////////////////////////////////
+void boxcomm_cpp1(void);
+
+////////////////////////////////////////////////////////////////////////////
+//// Fancier C++ style box comment.
+////
+//// This function has a very pretty C++ style box comment.
+////////////////////////////////////////////////////////////////////////////
+void boxcomm_cpp2(void);
diff --git a/eg/ccomment.h b/eg/ccomment.h
new file mode 100644
index 0000000..86bb7cd
--- /dev/null
+++ b/eg/ccomment.h
@@ -0,0 +1,41 @@
+/*
+** function starting with a C comment
+*/
+void ccomment(
+	/* single line before */
+	int single_before,
+
+	/*
+	 * multiple
+	 * lines before
+	 */
+	int multiple_before,
+
+	int end_of_line,	/* end of the line */
+
+	int multiple_eol,	/*
+				 * multiple lines
+				 * starting at
+				 * the EOL
+				 */
+
+	int single_eol_before_comma	/* end of line, but before comma */,
+
+	int multiple_eol_before_comma	/*
+					 * multiple lines after, at the EOL and
+					 * before comma.
+					 * can't imagine anyone coding this.
+					 */,
+
+	int single_after
+	/* single line after */
+	,
+
+	int multiple_after
+	/*
+	 * multiple lines
+	 * after.
+	 * can't imagine anyone coding like this.
+	 */
+);
+
diff --git a/eg/commentaft.c b/eg/commentaft.c
new file mode 100644
index 0000000..29e86d8
--- /dev/null
+++ b/eg/commentaft.c
@@ -0,0 +1 @@
+int commentafter;	/* you'll need -v to get this documented */
diff --git a/eg/cppcomment.h b/eg/cppcomment.h
new file mode 100644
index 0000000..2f4ff90
--- /dev/null
+++ b/eg/cppcomment.h
@@ -0,0 +1,32 @@
+//
+// function starting with a C++ comment
+//
+void cppcomment(
+	// single line before
+	int single_before,
+
+	//
+	// multiple
+	// lines before
+	//
+	int multiple_before,
+
+	int end_of_line,	// end of the line
+
+	int multiple_eol,	//
+				// multiple lines
+				// starting at
+				// the EOL
+				//
+
+	int single_after
+	// single line after
+	,
+	int multiple_after
+	//
+	// multiple lines
+	// after.
+	// cant imagine anyone coding like this.
+	//
+);
+
diff --git a/eg/dash.h b/eg/dash.h
new file mode 100644
index 0000000..bc3502b
--- /dev/null
+++ b/eg/dash.h
@@ -0,0 +1,2 @@
+/* dash - comment with a dash. */
+int dash(int x);
diff --git a/eg/ellipsis.c b/eg/ellipsis.c
new file mode 100644
index 0000000..0842f6a
--- /dev/null
+++ b/eg/ellipsis.c
@@ -0,0 +1,15 @@
+int             pr(int,...);
+
+void            main(void)
+{
+    pr(3, 'a', 'b', 'c');
+}
+
+/* ellipsis test function */
+int             pr(
+	int nitems,		/* number of items */
+	...			/* items */
+)
+{
+    /* blah, blah, blah, blah, blah! */
+}
diff --git a/eg/grouped.c b/eg/grouped.c
new file mode 100644
index 0000000..05f3a27
--- /dev/null
+++ b/eg/grouped.c
@@ -0,0 +1,23 @@
+/*
+ * grouped functions
+ *
+ */
+
+/* my grouped1 does something weird */
+grouped1(a,b)
+int a;	/* the a parameter */
+char b; /* the b parameter */
+{
+
+	/* do nothing */
+	return(1);
+}
+/* my grouped2 does also something weird */
+grouped2(a,b)
+int a;	/* the a parameter */
+char *b;/* the b parameter */
+{
+
+	/* do nothing */
+	return(1);
+}
diff --git a/eg/multidecl.c b/eg/multidecl.c
new file mode 100644
index 0000000..70ffa3f
--- /dev/null
+++ b/eg/multidecl.c
@@ -0,0 +1,3 @@
+int multidecl1,	/* the first one */
+    multidecl2,	/* the second one */
+    multidecl3;	/* the last one */
diff --git a/eg/namedash.h b/eg/namedash.h
new file mode 100644
index 0000000..6d05848
--- /dev/null
+++ b/eg/namedash.h
@@ -0,0 +1,9 @@
+/*
+ * NAME
+ *	namedash - name section with dash.
+ *
+ * DESCRIPTION
+ *	This function goes way over the top and includes a NAME section that
+ *	has a dash in it.
+ */
+int namedash();
diff --git a/eg/oldstyle.c b/eg/oldstyle.c
new file mode 100644
index 0000000..ec4bb8b
--- /dev/null
+++ b/eg/oldstyle.c
@@ -0,0 +1,24 @@
+/*
+** old-style function starting with a C comment
+*/
+void oldstyle(single_before, multiple_before, end_of_line, multiple_eol)
+
+/* single line before */
+int single_before;
+
+/*
+ * multiple
+ * lines before
+ */
+int multiple_before;
+
+int end_of_line;	/* end of the line */
+
+int multiple_eol;	/*
+			 * multiple lines
+			 * starting at
+			 * the EOL
+			 */
+{
+	/* blah, blah, blah, blah, blah! */
+}
diff --git a/eg/retdecl.c b/eg/retdecl.c
new file mode 100644
index 0000000..6675c8d
--- /dev/null
+++ b/eg/retdecl.c
@@ -0,0 +1,10 @@
+/* return near the declarator
+ * This is an example of embedding the `returns' information in near the
+ * declarator in a function declaration.
+ */
+char *			/* a string, or NULL if it failed */
+retdecl()
+{
+    /* reference implementation that barely meets the interface spec */
+    return NULL;
+}
diff --git a/eg/returnerr.h b/eg/returnerr.h
new file mode 100644
index 0000000..2292585
--- /dev/null
+++ b/eg/returnerr.h
@@ -0,0 +1,16 @@
+/*
+ * Do an operating system operation
+ * This is an example of a function which performs some sort of operating
+ * system operation, returning an errno-like indication of its success or
+ * failure.  We'd like the documentation to list all the possible failure
+ * indications that this function can return, which is only a tiny subset of
+ * all the possible errno values.  Hence, we don't define it as returning an
+ * enum of some sort, since that would cause c2man to list every possible value
+ * that type can have.
+ * Returns an indication of success or failure, as follows:
+ *	EOK: Success
+ *	EIO: I/O error
+ *	ENOMEM: Out of memory
+ *	EIEIO: Old Macdonald error
+ */
+int reterrno();
diff --git a/eg/returnlist.h b/eg/returnlist.h
new file mode 100644
index 0000000..819f652
--- /dev/null
+++ b/eg/returnlist.h
@@ -0,0 +1,16 @@
+/* generate a lot of silly values
+ * Returns: Quite a number of things, as follows:
+ *	0	nothing
+ *	1	something small
+ *	2	a little larger
+ *	3	done in triplicate
+ *	4	getting larger
+ *	5	quintuplets
+ *	6	that'll do now, although I think this one is going to get
+ *		very long and even cover multiple lines. let's just hope that
+ *		it gets it right, including the capitalisation. maybe this is
+ *		not a super thorough test, so including some
+ * .B bold
+ *		stuff might help
+ */
+int returnlist();
diff --git a/eg/sections.c b/eg/sections.c
new file mode 100644
index 0000000..8a84a00
--- /dev/null
+++ b/eg/sections.c
@@ -0,0 +1,17 @@
+/*
+ * NAME
+ *	sections - multisection function comment.
+ *
+ * DESCRIPTION
+ *	Only a mental cripple would be as verbose as this.
+ *
+ * WARNING
+ *	Now here's a legitimate excuse for it.
+ */
+int sections(
+	int fred,	/* Mary's boyfriend */
+	int world	/* real crazy */
+)
+{
+	what the heck, all this stuff just gets ignored
+}
diff --git a/eg/simplesect.c b/eg/simplesect.c
new file mode 100644
index 0000000..8d6f4ed
--- /dev/null
+++ b/eg/simplesect.c
@@ -0,0 +1,13 @@
+/*
+ * calculate some sections.
+ * Note: this becomes the description.
+ *
+ * Warning: This becomes a section.
+ */
+int simplesect(
+	int fred,	/* Mary's boyfriend */
+	int world	/* real crazy */
+)
+{
+	what the heck, all this stuff just gets ignored
+}
diff --git a/eg/surround.c b/eg/surround.c
new file mode 100644
index 0000000..e050056
--- /dev/null
+++ b/eg/surround.c
@@ -0,0 +1,6 @@
+/* surrounded by comments.
+ * this is the first one, and only it should be output.
+ *
+ * note: you'll need -v to get output from this.
+ */
+int surround;	/* this should NOT be output. */
diff --git a/eg/underscore.h b/eg/underscore.h
new file mode 100644
index 0000000..e57e6d5
--- /dev/null
+++ b/eg/underscore.h
@@ -0,0 +1,21 @@
+/* parameter names have underscores
+ * the underscores get removed in the documentation
+ */
+void underscore(
+    /* an int */
+    int __x,
+
+    /* a pointer to an int */
+    int *__y,
+
+    /* another pointer to an int, funnily enough */
+    int _z[],
+
+    /* a char, with a strange bit legal name */
+    char _,
+
+    /* an anonymous double */
+    double,
+
+    /* pointer to a function */
+    float (*__funcptr)(int *__a1, char __a2[]));
diff --git a/eg/variable.c b/eg/variable.c
new file mode 100644
index 0000000..a788e82
--- /dev/null
+++ b/eg/variable.c
@@ -0,0 +1,5 @@
+/* a variable, not a function.
+ *
+ * Note: you'll need to use -v to get this to work.
+ */
+int variable;