Documentation

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

15 files changed, 79 insertions, 4 deletions

diff --git a/libaxl/low-level.h b/libaxl/low-level.h
index 36449a2..30e13cc 100644
--- a/libaxl/low-level.h
+++ b/libaxl/low-level.h
@@ -47,7 +47,7 @@ LIBAXL_CONNECTION *libaxl_create(int);
  * is always LIBAXL_ERROR_SYSTEM
  */
 _LIBAXL_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
-LIBAXL_CONNECTION *libaxl_connect_without_handshake(const char *host, const char *protocol, int display, int screen); /* TODO man(makefile; ref libaxl_parse_display, libaxl_send_handshake, libaxl_connect) */
+LIBAXL_CONNECTION *libaxl_connect_without_handshake(const char *host, const char *protocol, int display, int screen); /* TODO man(makefile; ref libaxl_parse_display, libaxl_send_handshake, libaxl_connect; (ADVANCED)) */
 
 /**
  * Parse a display name string
@@ -148,7 +148,7 @@ int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const
  *                   LIBAXL_HANDSHAKE_SUCCESS.
  * @param   reasonp  Output parameter for the reason the handshake or authorisation
  *                   failed; the contents are specific to the authorisation protocol
- *                   in use Will be set to `NULL` unless the function returns
+ *                   in use. Will be set to `NULL` unless the function returns
  *                   LIBAXL_HANDSHAKE_FAILED or LIBAXL_HANDSHAKE_AUTHENTICATE.
  *                   Remember to free after successful completion (non-negative return)
  * @param   flags    Flags to use for the 4th parameter when calling recv(3)
diff --git a/man3/LIBAXL_PROTOCOL_VERSION.3 b/man3/LIBAXL_PROTOCOL_VERSION.3
index cdc2c94..b2bd11b 100644
--- a/man3/LIBAXL_PROTOCOL_VERSION.3
+++ b/man3/LIBAXL_PROTOCOL_VERSION.3
@@ -1,6 +1,7 @@
 .TH LIBAXL_PROTOCOL_VERSION 3 libaxl
 .SH NAME
 LIBAXL_PROTOCOL_VERSION - X protocol version
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 b/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3
index d8a0500..e6e74bc 100644
--- a/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3
+++ b/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3
@@ -1,6 +1,7 @@
 .TH LIBAXL_PROTOCOL_VERSION_MAJOR 3 libaxl
 .SH NAME
 LIBAXL_PROTOCOL_VERSION_MAJOR - X protocol version, major number
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 b/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3
index 5a2b975..76405e1 100644
--- a/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3
+++ b/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3
@@ -1,6 +1,7 @@
 .TH LIBAXL_PROTOCOL_VERSION_MINOR 3 libaxl
 .SH NAME
 LIBAXL_PROTOCOL_VERSION_MINOR - X protocol version, minor number
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_attach.3 b/man3/libaxl_attach.3
index 0ec4f8f..d4c3c07 100644
--- a/man3/libaxl_attach.3
+++ b/man3/libaxl_attach.3
@@ -1,6 +1,7 @@
 .TH libaxl_attach 3 libaxl
 .SH NAME
 libaxl_attach - Change file descriptor of a connection
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_create.3 b/man3/libaxl_create.3
index d29c32e..f1f7a97 100644
--- a/man3/libaxl_create.3
+++ b/man3/libaxl_create.3
@@ -1,6 +1,7 @@
 .TH libaxl_create 3 libaxl
 .SH NAME
 libaxl_create - Create connection record
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_detach.3 b/man3/libaxl_detach.3
index 39dfefb..4fbf46b 100644
--- a/man3/libaxl_detach.3
+++ b/man3/libaxl_detach.3
@@ -1,6 +1,7 @@
 .TH libaxl_detach 3 libaxl
 .SH NAME
 libaxl_detach - Deallocate but do not close connection
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_get_decnet_object.3 b/man3/libaxl_get_decnet_object.3
index 325b44c..1bade12 100644
--- a/man3/libaxl_get_decnet_object.3
+++ b/man3/libaxl_get_decnet_object.3
@@ -1,6 +1,7 @@
 .TH libaxl_get_decnet_object 3 libaxl
 .SH NAME
 libaxl_get_decnet_object - Get DECnet object name for a display
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_get_tcp_port.3 b/man3/libaxl_get_tcp_port.3
index 8041f78..6d39f0d 100644
--- a/man3/libaxl_get_tcp_port.3
+++ b/man3/libaxl_get_tcp_port.3
@@ -1,6 +1,7 @@
 .TH libaxl_get_tcp_port 3 libaxl
 .SH NAME
 libaxl_get_tcp_port - Get TCP port number for a display
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_parse_display.3 b/man3/libaxl_parse_display.3
index 82f1a67..47b034a 100644
--- a/man3/libaxl_parse_display.3
+++ b/man3/libaxl_parse_display.3
@@ -1,6 +1,7 @@
 .TH libaxl_parse_display 3 libaxl
 .SH NAME
 libaxl_parse_display - Parse a display name string
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_protocol_version.3 b/man3/libaxl_protocol_version.3
index 38f5871..cdfa0fd 100644
--- a/man3/libaxl_protocol_version.3
+++ b/man3/libaxl_protocol_version.3
@@ -1,6 +1,7 @@
 .TH libaxl_protocol_version 3 libaxl
 .SH NAME
 libaxl_protocol_version - X protocol version
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_protocol_version_major.3 b/man3/libaxl_protocol_version_major.3
index d16aa9d..892f122 100644
--- a/man3/libaxl_protocol_version_major.3
+++ b/man3/libaxl_protocol_version_major.3
@@ -1,6 +1,7 @@
 .TH libaxl_protocol_version_major 3 libaxl
 .SH NAME
 libaxl_protocol_version_major - X protocol version, major number
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_protocol_version_minor.3 b/man3/libaxl_protocol_version_minor.3
index 8610c15..f0ba2bd 100644
--- a/man3/libaxl_protocol_version_minor.3
+++ b/man3/libaxl_protocol_version_minor.3
@@ -1,6 +1,7 @@
 .TH libaxl_protocol_version_minor 3 libaxl
 .SH NAME
 libaxl_protocol_version_minor - X protocol version, minor number
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/man3/libaxl_receive_handshake.3 b/man3/libaxl_receive_handshake.3
index 855cdb7..a64167f 100644
--- a/man3/libaxl_receive_handshake.3
+++ b/man3/libaxl_receive_handshake.3
@@ -1,6 +1,7 @@
 .TH libaxl_receive_handshake 3 libaxl
 .SH NAME
 libaxl_receive_handshake - Finish connection handshake
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
@@ -25,7 +26,68 @@ The value of the
 parameter shall be the thread's state for the
 connection to the display server.
 .PP
-TODO majorp, minorp, reasonp
+If the
+.I majorp
+parameter is set to a
+.RI non- NULL
+pointer and the
+.BR libaxl_receive_handshake ()
+function returns
+.B LIBAXL_HANDSHAKE_SUCCESS
+or
+.BR LIBAXL_HANDSHAKE_FAILED ,
+.I *majorp
+will be set to the major version number for a
+version of the X protocol that the display server
+supports, which is not necessarily the version
+that the library uses.
+.PP
+If the
+.I minorp
+parameter is set to a
+.RI non- NULL
+pointer and the
+.BR libaxl_receive_handshake ()
+function returns
+.B LIBAXL_HANDSHAKE_SUCCESS
+or
+.BR LIBAXL_HANDSHAKE_FAILED ,
+.I *minorp
+will be set to the minor version number for the
+verison for which the major version number was
+returned in
+.I *majorp
+(or if
+.I majorp
+is
+.IR NULL :
+would have been returned).
+.PP
+If the
+.I reasonp
+parameter is set to a
+.RI non- NULL
+pointer and the
+.BR libaxl_receive_handshake ()
+function returns
+.B LIBAXL_HANDSHAKE_FAILED
+or
+.BR LIBAXL_HANDSHAKE_AUTHENTICATE ,
+.I *reasonp
+will be set to a dynamically allocated string
+(which the caller must deallocate with the
+.BR free (3)
+function) providing an authorisation
+protocol-specific reason which the handshake
+failed. If The
+.BR libaxl_receive_handshake ()
+function returns any other value, and the
+.I reasonp
+paramater is set to a
+.RI non- NULL ,
+.I *reasonp
+will be set to
+.IR NULL .
 .PP
 Flags to used in the fourth argument when the
 .BR libaxl_receive_handshake ()
@@ -40,7 +102,7 @@ The
 function return
 .B LIBAXL_HANDSHAKE_SUCCESS
 upon successful completion with successful handshake
-(beaware, this value is not 0),
+(beware, this value is not 0!),
 .B LIBAXL_HANDSHAKE_FAILURE
 upon successful completion with handshake failure,
 .B LIBAXL_HANDSHAKE_AUTHENTICATE
diff --git a/man3/libaxl_send_handshake.3 b/man3/libaxl_send_handshake.3
index 71f58fd..6068a0f 100644
--- a/man3/libaxl_send_handshake.3
+++ b/man3/libaxl_send_handshake.3
@@ -1,6 +1,7 @@
 .TH libaxl_send_handshake 3 libaxl
 .SH NAME
 libaxl_send_handshake - Initiate connection handshake
+.B (ADVANCED)
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>