From 38ced89fd9f856520a83833672cee0fe16eafcd2 Mon Sep 17 00:00:00 2001
From: bernie <bernie@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Thu, 5 Aug 2004 18:46:52 +0000
Subject: [PATCH] Documentation improvements.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@116 38d2e660-2303-0410-9eaa-f027e97ec537
---
 config_template.h   |  7 ++++--
 mware/text.h        | 21 ++++++++++++++----
 mware/text_format.c | 52 ++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/config_template.h b/config_template.h
index 7b3867e5..7bfcadd9 100755
--- a/config_template.h
+++ b/config_template.h
@@ -11,7 +11,7 @@
  * "config.h" and delete the CONFIG_ macros for the modules
  * you're not using.
  *
- * \para Working with multiple applications
+ * <h2>Working with multiple applications</h2>
  *
  * If your project is made of multiple DevLib-based applications,
  * create a custom "config.h" file in each application subdirectory
@@ -19,7 +19,7 @@
  * You can share common options by creationg a "config_common.h" header
  * and including it from all your "config.h" copies.
  *
- * \para Configuration style
+ * <h2>Configuration style</h2>
  *
  * For improved compile-time checking of configuration options,
  * the preferred way to use a \c CONFIG_ symbol is keeping it
@@ -46,6 +46,9 @@
 
 /*
  * $Log$
+ * Revision 1.2  2004/08/05 18:46:52  bernie
+ * Documentation improvements.
+ *
  * Revision 1.1  2004/07/29 23:34:32  bernie
  * Add template configuration file.
  *
diff --git a/mware/text.h b/mware/text.h
index 97eae956..74508b2a 100755
--- a/mware/text.h
+++ b/mware/text.h
@@ -14,6 +14,9 @@
 
 /*
  * $Log$
+ * Revision 1.3  2004/08/05 18:46:44  bernie
+ * Documentation improvements.
+ *
  * Revision 1.2  2004/06/03 11:27:09  bernie
  * Add dual-license information.
  *
@@ -25,27 +28,37 @@
 #include "compiler.h"
 #include <stdarg.h>
 
-/* Style flags */
+/*!
+ * \name Style flags
+ * \see text_style()
+ * \{
+ */
 #define STYLEF_BOLD        BV(0)
 #define STYLEF_ITALIC      BV(1)
 #define STYLEF_UNDERLINE   BV(2)
 #define STYLEF_INVERT      BV(3)
 #define STYLEF_EXPANDED    BV(4)
 #define STYLEF_CONDENSED   BV(5)
-#define STYLEF_STRIKEOUT   BV(6)  /* Not implemented */
+#define STYLEF_STRIKEOUT   BV(6)  /*<! Not implemented */
 
 #define STYLEF_MASK \
 	(STYLEF_BOLD | STYLEF_ITALIC | STYLEF_UNDERLINE | \
 	STYLEF_EXPANDED | STYLEF_CONDENSED | STYLEF_INVERT)
+/*\}*/
 
-/* Flags for text_xprintf() */
+/*!
+ * \name Formatting flags for text rendering
+ * \see text_xprintf()
+ * \{
+ */
 #define TEXT_NORMAL   0       /*!< Normal mode */
 #define TEXT_FILL     BV(0)   /*!< Fill rest of line with spaces */
 #define TEXT_CENTER   BV(1)   /*!< Center string in line */
 #define TEXT_INVERT   BV(2)   /*!< Inverted mode */
 #define TEXT_RIGHT    BV(3)   /*!< Right aligned */
+/*\}*/
 
-/* Escape sequences codes */
+/*! Escape sequences codes */
 #define ANSI_ESC_CLEARSCREEN 'c'
 
 
diff --git a/mware/text_format.c b/mware/text_format.c
index 5e73880f..954d1bc8 100755
--- a/mware/text_format.c
+++ b/mware/text_format.c
@@ -1,9 +1,8 @@
 /*!
  * \file
- *
  * <!--
+ * Copyright 2003, 2004 Develer S.r.l. (http://www.develer.com/)
  * Copyright 1999 Bernardo Innocenti <bernie@develer.com>
- * Copyright 2003,2004 Develer S.r.l. (http://www.develer.com/)
  * This file is part of DevLib - See devlib/README for information.
  * -->
  *
@@ -17,6 +16,9 @@
 
 /*
  * $Log$
+ * Revision 1.4  2004/08/05 18:46:44  bernie
+ * Documentation improvements.
+ *
  * Revision 1.3  2004/08/03 15:57:18  aleph
  * Add include to fix warning for vsprintf()
  *
@@ -43,7 +45,14 @@
 #include <string.h> /* strlen() */
 
 /*!
- * Render string <code>str</code> in bitmap
+ * Render string \a str in Bitmap \a bm at current cursor position
+ *
+ * \note Text formatting functions are also available with an _P suffix
+ *       accepting the source string from program memory.  This feature
+ *       is only available (and useful) on Harvard microprocessors such
+ *       as the AVR.
+ *
+ * \see text_putchar()
  */
 int PGM_FUNC(text_puts)(const char * PGM_ATTR str, struct Bitmap *bm)
 {
@@ -56,12 +65,30 @@ int PGM_FUNC(text_puts)(const char * PGM_ATTR str, struct Bitmap *bm)
 }
 
 
+/*!
+ * vprintf()-like formatter to render text in a Bitmap.
+ *
+ * Perform vprintf()-like formatting on the \a fmt format string using the
+ * variable-argument list \a ap.
+ * Render the resulting string in Bitmap \a bm starting at the current
+ * cursor position.
+ *
+ * \see text_puts() text_putchar() text_printf()
+ */
 int PGM_FUNC(text_vprintf)(struct Bitmap *bm, const char * PGM_ATTR fmt, va_list ap)
 {
 	return PGM_FUNC(_formatted_write)(fmt, (void (*)(char, void *))text_putchar, bm, ap);
 }
 
-
+/*!
+ * printf()-like formatter to render text in a Bitmap.
+ *
+ * Perform printf()-like formatting on the \a fmt format string.
+ * Render the resulting string in Bitmap \a bm starting at the
+ * current cursor position.
+ *
+ * \see text_puts() text_putchar() text_vprintf()
+ */
 int PGM_FUNC(text_printf)(struct Bitmap *bm, const char * PGM_ATTR fmt, ...)
 {
 	int len;
@@ -75,8 +102,23 @@ int PGM_FUNC(text_printf)(struct Bitmap *bm, const char * PGM_ATTR fmt, ...)
 }
 
 
+/*!
+ * Render the result of printf()-like formatting in a specified position
+ * of a Bitmap.
+ *
+ * \param bm Bitmap where to render the text
+ * \param row  Starting row in character units (zero based)
+ * \param col  Starting column in character units (zero based)
+ * \param mode Formatting mode to use.  Can be TEXT_NORMAL,
+ *        TEXT_FILL, TEXT_INVERT or TEXT_RIGHT or a combination
+ *        of these flags ORed together.
+ * \param fmt  String possibly containing printf() formatting commands.
+ *
+ * \see text_puts() text_putchar() text_printf() text_vprintf()
+ * \see text_moveto() text_style()
+ */
 int PGM_FUNC(text_xprintf)(struct Bitmap *bm,
-		uint8_t row, uint8_t col, uint8_t mode, const char * PGM_ATTR fmt, ...) 
+		uint8_t row, uint8_t col, uint8_t mode, const char * PGM_ATTR fmt, ...)
 {
 	int len;
 	uint8_t oldstyle = 0;
-- 
2.25.1