Documentation

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

7 files changed, 82 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index d6f0188..350285f 100644
--- a/Makefile
+++ b/Makefile
@@ -136,6 +136,8 @@ MAN3 =\
 	man3/LIBAXL_ATOM_WM_TRANSIENT_FOR.3\
 	man3/LIBAXL_ATOM_WM_ZOOM_HINTS.3\
 	man3/LIBAXL_ATOM_X_HEIGHT.3\
+	man3/LIBAXL_CONNECTION.3\
+	man3/LIBAXL_CONTEXT.3\
 	man3/LIBAXL_DECNET_OBJECT_MAX.3\
 	man3/LIBAXL_ERROR.3\
 	man3/LIBAXL_ERROR_ACCESS.3\
@@ -299,6 +301,8 @@ MAN3 =\
 	man3/libaxl_protocol_version_minor.3\
 	man3/libaxl_receive_handshake.3\
 	man3/libaxl_send_handshake.3\
+	man3/struct_libaxl_connection.3\
+	man3/struct_libaxl_context.3\
 	man3/struct_libaxl_error_access.3\
 	man3/struct_libaxl_error_alloc.3\
 	man3/struct_libaxl_error_atom.3\
diff --git a/TODO b/TODO
index f847558..a3db2f0 100644
--- a/TODO
+++ b/TODO
@@ -1,5 +1,6 @@
 Man pages: check italic–bold consistency
 Man pages: check values of constants
+Man pages: add linking instructions
 Add libaxl_marshal
 Add libaxl_unmarshal
 libaxl_close: guarantee that the file is closed
diff --git a/libaxl.h b/libaxl.h
index 36aa390..bff6b55 100644
--- a/libaxl.h
+++ b/libaxl.h
@@ -14,7 +14,7 @@
 /**
  * Opaque structure for connection to the X display server
  */
-typedef struct libaxl_connection LIBAXL_CONNECTION; /* TODO man(makefile) */
+typedef struct libaxl_connection LIBAXL_CONNECTION;
 
 /**
  * Opaque structure that wraps LIBAXL_CONNECTION with
@@ -22,7 +22,7 @@ typedef struct libaxl_connection LIBAXL_CONNECTION; /* TODO man(makefile) */
  * the same time shall access the display server
  * via a unique LIBAXL_CONTEXT
  */
-typedef struct libaxl_context LIBAXL_CONTEXT; /* TODO man(makefile) */
+typedef struct libaxl_context LIBAXL_CONTEXT;
 
 #include "libaxl/types.h"
 #include "libaxl/consts.h"
diff --git a/man3/LIBAXL_CONNECTION.3 b/man3/LIBAXL_CONNECTION.3
new file mode 100644
index 0000000..c8ebd66
--- /dev/null
+++ b/man3/LIBAXL_CONNECTION.3
@@ -0,0 +1,35 @@
+.TH LIBAXL_CONNECTION 3 libaxl
+.SH NAME
+LIBAXL_CONNECTION - Connection to display server
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+typedef struct libaxl_connection LIBAXL_CONNECTION;
+.fi
+.SH DESCRIPTION
+The
+.B LIBAXL_CONNECTION
+type definition (also known as
+.BR "struct libaxl_connection" )
+is used by the libaxl library to store the
+state of a connection to an X display server,
+as well as the connection itself to the
+display server.
+.PP
+The library only exposes an incomplete
+definition to of the structure because it
+should be regarded as opaque as it may change
+between versions of the library.
+.PP
+Using the
+.BR libaxl_connect (3)
+function is the easiest way to create a
+connection to the display server; it can
+be disposed with the
+.BR libaxl_close (3)
+function.
+.SH SEE ALSO
+.BR libaxl_connect (3),
+.BR libaxl_close (3),
+.BR LIBAXL_CONTEXT (3)
diff --git a/man3/LIBAXL_CONTEXT.3 b/man3/LIBAXL_CONTEXT.3
new file mode 100644
index 0000000..6b21224
--- /dev/null
+++ b/man3/LIBAXL_CONTEXT.3
@@ -0,0 +1,38 @@
+.TH LIBAXL_CONTEXT 3 libaxl
+.SH NAME
+LIBAXL_CONTEXT - Thread context for connection to display server
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+typedef struct libaxl_context LIBAXL_CONTEXT;
+.fi
+.SH DESCRIPTION
+The
+.B LIBAXL_CONTEXT
+type definition (also known as
+.BR "struct libaxl_context" )
+is used by the libaxl library to wrap a
+.BR LIBAXL_CONNECTION (3)
+object and store thread-private data.
+All threads running at the same time shall
+access the display server via a unique
+.B LIBAXL_CONTEXT
+object.
+.PP
+The library only exposes an incomplete
+definition to of the structure because it
+should be regarded as opaque as it may change
+between versions of the library.
+.PP
+The
+.BR libaxl_context_create (3)
+function is used to create a
+.B LIBAXL_CONTEXT
+object; it can be deallocated with the
+.BR libaxl_context_free (3)
+function.
+.SH SEE ALSO
+.BR libaxl_context_create (3),
+.BR libaxl_context_free (3),
+.BR LIBAXL_CONNECTION (3)
diff --git a/man3/struct_libaxl_connection.3 b/man3/struct_libaxl_connection.3
new file mode 120000
index 0000000..d3d4bd2
--- /dev/null
+++ b/man3/struct_libaxl_connection.3
@@ -0,0 +1 @@
+LIBAXL_CONNECTION.3
\ No newline at end of file
diff --git a/man3/struct_libaxl_context.3 b/man3/struct_libaxl_context.3
new file mode 120000
index 0000000..3db25e0
--- /dev/null
+++ b/man3/struct_libaxl_context.3
@@ -0,0 +1 @@
+LIBAXL_CONTEXT.3
\ No newline at end of file