Document the macros, structs, and enum

Signed-off-by: Mattias Andrée <m@maandree.se>

14 files changed, 169 insertions, 5 deletions

diff --git a/LIBJ2_J2I_BIT.3 b/LIBJ2_J2I_BIT.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/LIBJ2_J2I_BIT.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/LIBJ2_J2I_VBIT.3 b/LIBJ2_J2I_VBIT.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/LIBJ2_J2I_VBIT.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/LIBJ2_J2U_BIT.3 b/LIBJ2_J2U_BIT.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/LIBJ2_J2U_BIT.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/LIBJ2_JU_BIT.3 b/LIBJ2_JU_BIT.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/LIBJ2_JU_BIT.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/Makefile b/Makefile
index ff45328..253b500 100644
--- a/Makefile
+++ b/Makefile
@@ -458,7 +458,19 @@ LOBJ = $(OBJ:.o=.lo)
 TOBJ = $(OBJ:.o=.to)
 TEST = $(OBJ:.o=.t)
 
+MAN0 = libj2.h.0
 MAN7 = libj2.7
+MAN3 =\
+	LIBJ2_JU_BIT.3\
+	LIBJ2_J2U_BIT.3\
+	LIBJ2_J2I_BIT.3\
+	LIBJ2_J2I_VBIT.3\
+	struct_libj2_j2u.3\
+	libj2_j2u.3\
+	struct_libj2_j2i.3\
+	libj2_j2i.3\
+	enum_libj2_overflow.3\
+	libj2_overflow.3
 
 
 all: libj2.a libj2.$(LIBEXT) $(TEST)
@@ -500,6 +512,8 @@ check: $(TEST)
 install: libj2.a libj2.$(LIBEXT)
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/include/libj2"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man0"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
 	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7"
 	cp -- libj2.a "$(DESTDIR)$(PREFIX)/lib/"
 	cp -- libj2.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libj2.$(LIBMINOREXT)"
@@ -508,7 +522,9 @@ install: libj2.a libj2.$(LIBEXT)
 	ln -sf -- libj2.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libj2.$(LIBEXT)"
 	cp -- libj2.h "$(DESTDIR)$(PREFIX)/include/"
 	cp -- $(SUBHDR) "$(DESTDIR)$(PREFIX)/include/libj2/"
-	cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/"
+	cp -P -- $(MAN0) "$(DESTDIR)$(MANPREFIX)/man0/"
+	cp -P -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/"
+	cp -P -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/"
 
 uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libj2.a"
@@ -518,6 +534,8 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/libj2.h"
 	-cd -- "$(DESTDIR)$(PREFIX)/include/" && rm -f -- $(SUBHDR)
 	-rmdir -- "$(DESTDIR)$(PREFIX)/include/libj2"
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man0/" && rm -f -- $(MAN0)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -f -- $(MAN3)
 	-cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -f -- $(MAN7)
 
 clean:
diff --git a/enum_libj2_overflow.3 b/enum_libj2_overflow.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/enum_libj2_overflow.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/libj2.7 b/libj2.7
index ed03c6f..a5976e5 100644
--- a/libj2.7
+++ b/libj2.7
@@ -3,7 +3,8 @@
 libj2 \- Double-max precision integers
 
 .SH SYNOPSIS
-.nf #include <libj2.h>
+.nf
+#include <libj2.h>
 .fi
 .PP
 Link with
@@ -1003,4 +1004,5 @@ Calculate the remainder of the integer division between two
 values. This function swaps the position of the two operands.
 
 .SH SEE ALSO
+.BR libj2.h (0),
 .BR libzahl (7)
diff --git a/libj2.h b/libj2.h
index 58e4fbf..c351e43 100644
--- a/libj2.h
+++ b/libj2.h
@@ -67,7 +67,7 @@ struct libj2_j2u {
 	/**
 	 * Most significant half
 	 */
-        uintmax_t high;
+	uintmax_t high;
 
 	/**
 	 * Least significant half
@@ -98,7 +98,7 @@ struct libj2_j2i {
 	 * Most significant half, of which the most
 	 * significant bit is the sign bit
 	 */
-        uintmax_t high;
+	uintmax_t high;
 
 	/**
 	 * Least significant half
@@ -131,7 +131,7 @@ enum libj2_overflow {
 	 * Overflow prediction stopped
 	 * (due to high cost)
 	 */
-	LIBJ2_OVERFLOW_UNKNOWN
+	LIBJ2_OVERFLOW_UNKNOWN = 2
 };
 
 
diff --git a/libj2.h.0 b/libj2.h.0
new file mode 100644
index 0000000..b9e434e
--- /dev/null
+++ b/libj2.h.0
@@ -0,0 +1,134 @@
+.TH LIBJ2.H 0 LIBJ2
+.SH NAME
+libj2.h \- Double-max precision integers header file
+
+.SH SYNOPSIS
+.nf
+#include <libj2.h>
+
+#define \fBLIBJ2_JU_BIT\fP   /* implementation omitted */
+#define \fBLIBJ2_J2U_BIT\fP  (2U * LIBJ2_JU_BIT)
+#define \fBLIBJ2_J2I_BIT\fP  LIBJ2_J2U_BIT
+#define \fBLIBJ2_J2I_VBIT\fP (LIBJ2_J2I_BIT - 1U)
+
+\fBstruct libj2_j2u\fP {
+	uintmax_t \fIhigh\fP;
+	uintmax_t \fIlow\fP;
+};
+
+\fBstruct libj2_j2i\fP {
+	uintmax_t \fIhigh\fP;
+	uintmax_t \fIlow\fP;
+};
+
+\fBenum libj2_overflow\fP {
+	\fBLIBJ2_NO_OVERFLOW\fP = 0,
+	\fBLIBJ2_OVERFLOW\fP = 1,
+	\fBLIBJ2_OVERFLOW_UNKNOWN\fP = 2
+};
+
+.fi
+.PP
+Link with
+.IR -lj2 .
+
+.SH DESCRIPTION
+The
+.B libj2.h
+header file, provides definitions used for the
+.B libj2
+double-max precision integer library.
+.PP
+The header file defines the type
+.B struct\ libj2_j2u
+for unsigned integers with double the width of
+.BR uintmax_t ,
+and the type
+.B struct\ libj2_j2i
+for signed integers with the same width, including
+one bit for signess.
+.B struct\ libj2_j2i
+uses two's complement, and is designed to be
+storage-wise identical to
+.BR struct\ libj2_j2u .
+It is guaranteed for both types that,
+.I high
+is the first member, and
+.I low
+is the second member, and that those are the only
+members, of the
+.IR struct s.
+.I high
+stores the most significant half, including the
+sign-bit as the most significant bit for
+.BR struct\ libj2_j2i ,
+and
+.I low
+stores the least significant half.
+Each half stores
+.B LIBJ2_JU_BIT
+bits, for a sum of
+.B LIBJ2_J2U_BIT
+bits for the entire
+.I struct .
+.PP
+.B LIBJ2_J2I_BIT
+is a synonym for
+.BR LIBJ2_J2U_BIT .
+.B LIBJ2_J2I_BIT
+is preferable in the context of the width of
+.BR struct\ libj2_j2i ,
+whereas
+.B LIBJ2_J2U_BIT
+is preferable in the context of the width of
+.BR struct\ libj2_j2u .
+.PP
+.B LIBJ2_J2I_VBIT
+specifies the number of value-bits in a
+.BR struct\ libj2_j2i ,
+that is, the number of bits it holds less
+the sign-bit.
+.PP
+.BR LIBJ2_JU_BIT ,
+.BR LIBJ2_J2U_BIT ,
+.BR LIBJ2_J2I_BIT ,
+and
+.B LIBJ2_J2I_VBIT
+are compile-time constants, but not
+preprocessor-time constants.
+.PP
+.B enum\ libj2_overflow
+is used as the return-type by some
+overflow-prediction functions.
+.B LIBJ2_NO_OVERFLOW
+signifies that the result is fully representable.
+.B LIBJ2_OVERFLOW
+signifies that the result is positive but too large
+to be fully represented.
+.B LIBJ2_OVERFLOW_UNKNOWN
+signifies that the function bailed out making the
+overflow prediction, but that the result is positive.
+.PP
+See
+.BR libj2 (7)
+for a listing of functions defined by the
+header file.
+
+.SH HISTORY
+.BR LIBJ2_JU_BIT ,
+.BR LIBJ2_J2U_BIT ,
+.BR struct\ libj2_j2u ,
+and
+.B enum\ libj2_overflow
+where added in version 1.0 of
+.BR libj2 .
+.PP
+.BR LIBJ2_J2I_BIT ,
+.BR LIBJ2_J2I_VBIT ,
+and
+.B struct\ libj2_j2i
+where added in version 1.1 of
+.BR libj2 .
+
+.SH SEE ALSO
+.BR libj2 (7)
diff --git a/libj2_j2i.3 b/libj2_j2i.3
new file mode 120000
index 0000000..fcc4984
--- /dev/null
+++ b/libj2_j2i.3
@@ -0,0 +1 @@
+struct_libj2_j2i.3
\ No newline at end of file
diff --git a/libj2_j2u.3 b/libj2_j2u.3
new file mode 120000
index 0000000..07f2959
--- /dev/null
+++ b/libj2_j2u.3
@@ -0,0 +1 @@
+struct_libj2_j2u.3
\ No newline at end of file
diff --git a/libj2_overflow.3 b/libj2_overflow.3
new file mode 120000
index 0000000..b5cd9d7
--- /dev/null
+++ b/libj2_overflow.3
@@ -0,0 +1 @@
+enum_libj2_overflow.3
\ No newline at end of file
diff --git a/struct_libj2_j2i.3 b/struct_libj2_j2i.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/struct_libj2_j2i.3
@@ -0,0 +1 @@
+.so libj2.h.0
diff --git a/struct_libj2_j2u.3 b/struct_libj2_j2u.3
new file mode 100644
index 0000000..0d413b8
--- /dev/null
+++ b/struct_libj2_j2u.3
@@ -0,0 +1 @@
+.so libj2.h.0