Partial cleanup of argument count validation in mdoc(7):

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index 49bd4f6be387dfd05337ba03bb561c08733e96f0..c19b301757a7ad15e70ce8ab21253dd51c85f549 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.3,v 1.52 2011/01/01 12:18:37 kristaps Exp $
+.\"    $Id: mdoc.3,v 1.54 2011/01/03 13:55:26 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: January 1 2011 $
+.Dd $Mdocdate: January 3 2011 $

 .Dt MDOC 3
 .Os
 .Sh NAME
 .Dt MDOC 3
 .Os
 .Sh NAME


@@ -96,6 +96,16 @@ See
 for details.
 .El
 .Ss Functions
 for details.
 .El
 .Ss Functions

+If
+.Fn mdoc_addspan ,
+.Fn mdoc_parseln ,
+or
+.Fn mdoc_endparse
+return 0, calls to any function but
+.Fn mdoc_reset
+or
+.Fn mdoc_free
+will raise an assertion.

 .Bl -ohang
 .It Fn mdoc_addspan
 Add a table span to the parsing stream.
 .Bl -ohang
 .It Fn mdoc_addspan
 Add a table span to the parsing stream.


@@ -106,8 +116,8 @@ The
 .Fa data
 pointer is passed to
 .Fa msgs .
 .Fa data
 pointer is passed to
 .Fa msgs .

-Returns NULL on failure.
-If non-NULL, the pointer must be freed with
+Always returns a valid pointer.
+The pointer must be freed with

 .Fn mdoc_free .
 .It Fn mdoc_reset
 Reset the parser for another parse routine.
 .Fn mdoc_free .
 .It Fn mdoc_reset
 Reset the parser for another parse routine.


@@ -127,26 +137,11 @@ The input buffer
 is modified by this function.
 .It Fn mdoc_endparse
 Signals that the parse is complete.
 is modified by this function.
 .It Fn mdoc_endparse
 Signals that the parse is complete.

-Note that if
-.Fn mdoc_endparse
-is called subsequent to
-.Fn mdoc_node ,
-the resulting tree is incomplete.

 Returns 0 on failure, 1 on success.
 .It Fn mdoc_node
 Returns the first node of the parse.
 Returns 0 on failure, 1 on success.
 .It Fn mdoc_node
 Returns the first node of the parse.

-Note that if
-.Fn mdoc_parseln
-or
-.Fn mdoc_endparse
-return 0, the tree will be incomplete.

 .It Fn mdoc_meta
 Returns the document's parsed meta-data.
 .It Fn mdoc_meta
 Returns the document's parsed meta-data.

-If this information has not yet been supplied or
-.Fn mdoc_parseln
-or
-.Fn mdoc_endparse
-return 0, the data will be incomplete.

 .El
 .Ss Variables
 .Bl -ohang
 .El
 .Ss Variables
 .Bl -ohang