From 566d01a09c3e94781529b64f8b98516e922ee708 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Szabolcs=20Horva=CC=81t?= <szhorvat@gmail.com>
Date: Mon, 6 Nov 2017 17:26:43 +0100
Subject: [PATCH] mlstream: documentation improvements

---
 LTemplate/IncludeFiles/mlstream.h | 46 +++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/LTemplate/IncludeFiles/mlstream.h b/LTemplate/IncludeFiles/mlstream.h
index dc25632..14fc2ef 100644
--- a/LTemplate/IncludeFiles/mlstream.h
+++ b/LTemplate/IncludeFiles/mlstream.h
@@ -77,7 +77,11 @@ static_assert(sizeof(int) == 4 ,    "MathLink type size mismatch: sizeof(int) !=
 static_assert(sizeof(mlint64) == 8, "MathLink type size mismatch: sizeof(mlint64) != 8.");
 
 
-/// Wrapper for `MLINK` to allow using extractors and inserters
+/** \brief Wrapper for `MLINK` to allow using extractors and inserters
+ *
+ *  \param link is the MLINK object to wrap
+ *  \param context is a string that will be prepended to any message reported using error()
+ */
 class mlStream {
     MLINK lp;
     std::string context;
@@ -107,7 +111,7 @@ class mlStream {
 
 // Special
 
-/// Must be the first item extracted from mlStream, checks number of arguments and prepares for reading them.
+/// Must be the first item extracted from an mlStream, checks number of arguments and prepares for reading them.
 struct mlCheckArgs {
     int argc;
 
@@ -130,8 +134,16 @@ inline mlStream & operator >> (mlStream &ml, const mlCheckArgs &ca) {
 }
 
 
-/// Used for inserting a head with the given argument count into mlStream.
-/** Tyically used with the head List when returning multiple results. */
+/** \brief Used for inserting a head with the given argument count into an mlStream.
+ *
+ * Typically used with the head `List` when returning multiple results.
+ *
+ * The following example returns the complex number `3 - 2I`.
+ *
+ * \code
+ * ml << mlHead("Complex", 2) << 3 << -2;
+ * \endcode
+ */
 struct mlHead {
     const char *head;
     int argc;
@@ -149,7 +161,20 @@ inline mlStream & operator << (mlStream &ml, const mlHead &head) {
 }
 
 
-/// Used for inserting a symbol into mlStream
+/** \brief Used for inserting a symbol into an mlStream
+ *
+ * The following example returns `True` or `False` based on a Boolean variable.
+ *
+ * \code
+ * mlStream ml(link);
+ * bool b;
+ * // ...
+ * ml.newPacket();
+ * ml << (b ? mlSymbol("True") : mlSymbol("False"));
+ * \endcode
+ *
+ * While this is convenient for a single result, Boolean arrays are much faster to transfer as integers.
+ */
 struct mlSymbol {
     const char *symbol;
 
@@ -166,7 +191,15 @@ inline mlStream & operator << (mlStream &ml, const mlSymbol &symbol) {
 }
 
 
-/// Used for discarding a given number of expressions from an mlStream
+/** \brief Used for discarding a given number of expressions from an mlStream
+ *
+ * The following example reads 3 arguments, but does not use the second one.
+ *
+ * \code
+ * mlStream ml(link);
+ * ml >> mlCheckArgs(3) >> x >> mlDiscard() >> y;
+ * \endcode
+ */
 struct mlDiscard {
     const int count;
     explicit mlDiscard(int count = 1) : count(count) { }
@@ -259,6 +292,7 @@ inline mlStream & operator << (mlStream &ml, const char *s) {
     return ml;
 }
 
+
 // TensorRef
 
 inline mlStream & operator << (mlStream &ml, mma::IntTensorRef t) {