Add section on using dejagnu.h for unit testing.

3 files changed, 157 insertions, 5 deletions

diff --git a/doc/overview.sgml b/doc/overview.sgml
index 32b4b2e..e358fee 100644
--- a/doc/overview.sgml
+++ b/doc/overview.sgml
@@ -4,7 +4,7 @@
 
 <?Fm: Validation Off>
 
-<!ENTITY version "1.4">
+<!ENTITY version "1.4.1">
 <!ENTITY dj "DejaGnu">
 
 <!ENTITY dejagnu-copyright "
@@ -15,7 +15,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 This file documents the GNU Testing Framework ``DejaGnu''
 
-Copyright (C) 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software
+Copyright (C) 92 - 2000, 2001 Free Software
 Foundation, Inc.
 
 This text may be freely distributed under the terms of the GNU
@@ -24,7 +24,7 @@ General Public License.
 ">
 
 <!ENTITY dejagnu-copyright "
-Copyright 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software
+Copyright 92 - 2000, 2001 Free Software
 Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -54,9 +54,9 @@ into another language, under the above conditions for modified versions.
   <bookinfo>
     <title>&dj;</title>
     <subtitle>The GNU Testing Framework</subtitle>
-    <date>2001 Feb 16</date>
+    <date>2001 May 2</date>
     <edition> &version</edition>
-    <releaseinfo> for circulation within Cygnus</releaseinfo>
+    <releaseinfo> New release</releaseinfo>
     <authorgroup>
       <author>
         <firstname>Rob Savoye</firstname>
@@ -86,6 +86,12 @@ into another language, under the above conditions for modified versions.
     <!-- </legalnotice> -->
     <revhistory>
       <revision>
+        <revnumber>0.6.1</revnumber>
+        <date>2001-2-16</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Add info on the new dejagnu.h file.</revremark>
+      </revision>
+      <revision>
         <revnumber>0.6</revnumber>
         <date>2001-2-16</date>
         <authorinitials>rob@welcomehome.org</authorinitials>
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 6e0c9f5..f8f0ea7 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -4252,12 +4252,119 @@
       <listitem><para>lib/util-defs.exp</para></listitem>
       <listitem><para>lib/utils.exp</para></listitem>
       <listitem><para>lib/xsh.exp</para></listitem>
+      <listitem><para>lib/dejagnu.exp</para></listitem>
     </itemizedlist>
 
   </sect1>
 
 </chapter>
 
+<chapter id=unittesting>
+  <title>Unit Testing</title>
+
+  <sect1 id=unittestapi xreflabel="Unit Testing API">
+    <title>Unit Testing API</title>
+
+    <para>For unit testing, you can use the dejagnu.h header file. </para>
+    
+    <sect2 id=cunit xreflabel="C Unit Testing API">
+    <title>C Unit Testing API</title>
+    
+    <para>For C code, there is a C API.</para>
+    
+    <sect3 id=passfunc xreflabel="pass function">
+    <title>Pass Method</title>
+	  
+	  <para>This prints a message for a successful test
+	  completion.
+	  <parameter>msg</parameter>. This is a C char * string that
+	  is the message to be dislayed.</para>
+
+	  <funcsynopsis role="C"> 
+	  <funcdef><function>pass</function></funcdef>
+	  <paramdef><parameter>msg</parameter></paramdef>
+	  </funcsynopsis>
+    </sect3>
+    </sect2>
+
+    <sect2 id=cppunit xreflabel="C++ Unit Testing API">
+	   <title>C++ Unit Testing API</title>
+
+	   <sect3 id=passmeth xreflabel="pass method">
+	   <title>Pass Method</title>
+
+	  <para>This prints a message for a successful test
+	  completion.
+	  <parameter>msg</parameter>. This is a C char * string that
+	  is the message to be dislayed.</para>
+
+	<funcsynopsis role="C++"> 
+            <funcdef><function>TestState::pass</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=failmeth xreflabel="fail method">
+	  <title>Fail Method</title>
+
+	  <para>This prints a message for an unsuccessful test
+	  completion.
+	  <parameter>msg</parameter>. This is a C char * string that
+	  is the message to be dislayed.</para>
+
+	<funcsynopsis role="C++"> 
+            <funcdef><function>TestState::fail</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=untestedmeth xreflabel="untested method">
+	  <title>Untested Method</title>
+
+	  <para>This prints a message for an test case that isn't run
+	  for some technical reason.
+	  <parameter>msg</parameter>. This is a C char * string that
+	  is the message to be dislayed.</para>
+
+	<funcsynopsis role="C++"> 
+            <funcdef><function>TestState::untested</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=unresolvedmeth xreflabel="unresolved method">
+	  <title>Unresolved Method</title>
+
+	  <para>This prints a message for an test case that is run,
+	  but there is no clear result. These output states require a
+	  human to look over the results to determine what happened.
+	  <parameter>msg</parameter>. This is a C char * string that
+	  is the message to be dislayed.</para>
+
+	<funcsynopsis role="C++"> 
+            <funcdef><function>TestState::unresolved</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=totalsmeth xreflabel="totals method">
+	  <title>Totals Method</title>
+
+	  <para>This prints out the total numbers of all the test
+	  state outputs.</para>
+
+	<funcsynopsis role="C++"> 
+            <funcdef><function>TestState::totals</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+     </sect2>
+
+   </sect1>
+
+</chapter>
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/doc/user.sgml b/doc/user.sgml
index 7c38d4d..16f2160 100644
--- a/doc/user.sgml
+++ b/doc/user.sgml
@@ -2362,6 +2362,45 @@
    
 </chapter>
 
+  <chapter id=unit xreflabel="Unit Testing">
+    <title>Unit Testing</title>
+    
+    <sect1 id=unittest  xreflabel="What Is Unit Testing ?">
+      <title>What Is Unit Testing ?</title>
+    
+      <para>Most regression testing as done by DejaGnu is system
+      testing. This is the complete application is tested all at
+      once. Unit testing is for testing single files, or small
+      libraries. In this case, each file is linked with a test case in
+      C or C++, and each function or class and method is tested in
+      series, with the test case having to check private data or
+      global variable to see if the function or method worked.</para>
+
+      <para>This works particularly well for testing API and a level
+      where it is easier to debug them, than by need to trace through
+      the entire appication. Also if there is a specification for the
+      API to be tested, the testcase can also function as a compliance
+      test.</para>
+
+    </sect1>
+
+    <sect1 id=djh xreflabel="The dejagnu.h Header File">
+      <title>The dejagnu.h Header File</title>
+    
+      <para>DejaGnu uses a single header file to assist in unit
+      testing. As this file also produces it's one test state output,
+      it can be run standalone, which is very useful for testing on
+      embedded systems. This header file has a C and C++ API for the
+      test states, with simple totals, and standardized
+      output. Because the output has been standardized, DejaGnu can be
+      made to work with this test case, without writing almost any
+      Tcl. The library module, dejagnu.exp, will look for the output
+      messages, and then merge them into DejaGnu's.</para>
+
+     </sect1>
+ 
+</chapter>
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml