Updating documentation.

door.cpp

@@ -49,10 +49,24 @@ work-around code.
 
 namespace door {
 
+/**
+ * @brief convert string to lowercase
+ *
+ * @param text
+ */
 void to_lower(std::string &text) {
   transform(text.begin(), text.end(), text.begin(), ::tolower);
 }
 
+/**
+ * @brief Replace all instances of from with to.
+ *
+ * @param str
+ * @param from
+ * @param to
+ * @return true
+ * @return false
+ */
 bool replace(std::string &str, const std::string &from, const std::string &to) {
   size_t start_pos = str.find(from);
   if (start_pos == std::string::npos)
@@ -61,6 +75,15 @@ bool replace(std::string &str, const std::string &from, const std::string &to) {
   return true;
 }
 
+/**
+ * @brief Replace all instances of from with to.
+ *
+ * @param str
+ * @param from
+ * @param to
+ * @return true
+ * @return false
+ */
 bool replace(std::string &str, const char *from, const char *to) {
   size_t start_pos = str.find(from);
   if (start_pos == std::string::npos)
@@ -71,6 +94,11 @@ bool replace(std::string &str, const char *from, const char *to) {
 
 static bool hangup = false;
 
+/**
+ * @brief Signal handler for detecting hangup/broken pipe
+ *
+ * @param signal
+ */
 void sig_handler(int signal) {
   hangup = true;
   /*
@@ -83,6 +111,10 @@ void sig_handler(int signal) {
   // 13 SIGPIPE -- ok, what do I do with this, eh?
 }
 
+/**
+ * @brief Converts from one encoding to another.
+ * Uses iconv (international conversion) API.
+ */
 class IConv {
   iconv_t ic;
 
@@ -93,9 +125,25 @@ public:
   int convert(char *input, char *output, size_t outbufsize);
 };
 
+/**
+ * @brief Construct a new IConv::IConv object
+ * 
+ * Give the encodings that you want to convert to and from.
+ * @param to 
+ * @param from 
+ */
 IConv::IConv(const char *to, const char *from) : ic(iconv_open(to, from)) {}
 IConv::~IConv() { iconv_close(ic); }
 
+/**
+ * @brief Calls iconv API to do the conversion.
+ * 
+ * Buffers must be provided.
+ * @param input 
+ * @param output 
+ * @param outbufsize 
+ * @return int 
+ */
 int IConv::convert(char *input, char *output, size_t outbufsize) {
   size_t inbufsize = strlen(input);
   // size_t orig_size = outbufsize;
@@ -106,8 +154,18 @@ int IConv::convert(char *input, char *output, size_t outbufsize) {
   return r;
 }
 
+/**
+ * @brief converter that we provide to convert from CP437 to UTF-8.
+ * \re cp437toUnicode
+ */
 static IConv converter("UTF-8", "CP437");
 
+/**
+ * @brief Convert from CP437 to unicode.
+ *
+ * @param input
+ * @param out
+ */
 void cp437toUnicode(std::string input, std::string &out) {
   char buffer[10240];
   char output[16384];
@@ -117,6 +175,12 @@ void cp437toUnicode(std::string input, std::string &out) {
   out.assign(output);
 }
 
+/**
+ * @brief Convert from CP437 to unicode.
+ *
+ * @param input
+ * @param out
+ */
 void cp437toUnicode(const char *input, std::string &out) {
   char buffer[10240];
   char output[16384];
@@ -126,8 +190,23 @@ void cp437toUnicode(const char *input, std::string &out) {
   out.assign(output);
 }
 
+/**
+ * @brief Was unicode detected?
+ */
 bool unicode = false;
+/**
+ * @brief Was full CP437 detected?
+ *
+ * This is for full CP437 support, meaning it also supports hearts, diamonds,
+ * spades, clubs char(3)..char(6).  These are sometimes ignored by CP437
+ * translation programs as control codes.
+ */
 bool full_cp437 = false;
+/**
+ * @brief Capture the output for debugging.  
+ * 
+ * This is used by the tests.
+ */
 bool debug_capture = false;
 
 /**
@@ -1218,7 +1297,13 @@ std::ostream &operator<<(std::ostream &os, const Goto &g) {
   return os;
 }
 
+/**
+ * @brief ANSI Save Cursor position command.
+ */
 const char SaveCursor[] = "\x1b[s";
+/**
+ * @brief ANSI Restore Cursor position command.
+ */
 const char RestoreCursor[] = "\x1b[u";
 
 // EXAMPLES

door.h

@@ -709,6 +709,9 @@ public:
 class Screen {
 private:
   // bool hidden;
+  /**
+   * @brief vector of panels.
+   */
   std::vector<std::unique_ptr<Panel>> panels;
 
 public:

doxy.config

@@ -162,7 +162,7 @@ FILE_PATTERNS          = *.c \
                          *.ucf \
                          *.qsf
 RECURSIVE              = NO
-EXCLUDE                =
+EXCLUDE                = anyoption.h anyoption.cpp
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
 EXCLUDE_SYMBOLS        =

getkey.cpp

@@ -15,27 +15,32 @@
  * @brief Key and door input routines
  */
 
+/*
 void done(int signal) {
   std::cout << "\r\nWORP WORP\r\n";
   std::cout.flush();
 }
+*/
 
 #include <ctype.h>
 
+/**
+ * @brief Original terminal termios defaults.
+ */
 struct termios tio_default;
 
+/**
+ * @brief Enable terminal raw mode.
+ *
+ * This sets up the linux console so the door library will work correctly in
+ * local mode.
+ */
 void raw(void) {
   // enable terminal RAW mode
   struct termios tio_raw;
   tcgetattr(STDIN_FILENO, &tio_default);
   tio_raw = tio_default;
   cfmakeraw(&tio_raw);
-  /*
-  This works in the console, but fails with a terminal.
-  Ok, I am getting (what I would expect), but we're never timing out
-  now.  (So it has to fill up the buffer before exiting...)
-  CRAP!
-  */
 
   // Ok!  I need the extra sauce here
 
@@ -47,13 +52,29 @@ void raw(void) {
   tcsetattr(STDIN_FILENO, TCSANOW, &tio_raw);
 }
 
+/**
+ * @brief Reset the terminal termios to the original values.
+ */
 void reset(void) { tcsetattr(STDIN_FILENO, TCOFLUSH, &tio_default); }
 
+/**
+ * @brief used by output routines.
+ *
+ * Sending "\n" isn't enough.
+ */
 #define CRNL "\r\n"
 
 /*
 NOTE:  cr (from syncterm), gives 0x0d 0x00
+ */
 
+/**
+ * @brief low level getch key read
+ *
+ * This reads a key with a defined timeout value.
+ * This is called by other routines to handle arrow keys, F-keys.
+ * returns -1 on timeout (no key), -2 on error (connection closed)
+ * @return signed int
  */
 signed int getch(void) {
   fd_set socket_set;
@@ -89,9 +110,22 @@ signed int getch(void) {
   return key;
 }
 
+/**
+ * @brief pushback buffer to store keys we're not ready for yet.
+ */
 char buffer[10];
+/**
+ * @brief pushback buffer position 
+ */
 int bpos = 0;
 
+/**
+ * @brief ungets (pushes key back)
+ *
+ * If we read ahead, and we can't use it, we push it back into the buffer for
+ * next time.
+ * @param c
+ */
 void unget(char c) {
   if (bpos < sizeof(buffer) - 1) {
     buffer[bpos] = c;
@@ -99,6 +133,11 @@ void unget(char c) {
   }
 }
 
+/**
+ * @brief get a key from the pushback buffer.
+ * 
+ * @return char 
+ */
 char get(void) {
   if (bpos == 0) {
     return 0;
@@ -108,9 +147,19 @@ char get(void) {
   return c;
 }
 
+/**
+ * @brief high level getkey
+ * 
+ * This returns function keys, arrow keys, see XKEY_* defines.
+ * returns -1 (no key avaiable) or -2 (hangup)
+ * or XKEY_UNKNOWN (don't know what it is)
+ * 
+ * @return signed int 
+ */
 signed int getkey(void) {
   signed int c, c2;
 
+  // consume pushback buffer before reading more keys.
   if (bpos != 0) {
     c = get();
   } else {
@@ -158,7 +207,7 @@ signed int getkey(void) {
     }
 
     // FUTURE:  Display debug when we fail to identify the key
-#ifdef DEBUGGS
+#ifdef DEBUG_OUTPUT
     std::cout << CRNL "DEBUG:" CRNL "ESC + ";
     for (int x = 0; x < pos; x++) {
       char z = extended[x];

panel.cpp

@@ -141,6 +141,13 @@ struct box_styles {
  * This holds the characters needed to render the different box styles.
  * tl tr top side bl br ml mr
  */
+
+/**
+ * @brief Unicode box characters
+ *
+ * top-left, top-right, top, side, bottom-left, bottom-right, middle-left,
+ * middle-right See \ref BorderStyle for the order the boxes are in.
+ */
 struct box_styles UBOXES[] = {{"\u250c", "\u2510", "\u2500", "\u2502", "\u2514",
                                "\u2518", "\u251c", "\u2524"},
                               {"\u2554", "\u2557", "\u2550", "\u2551", "\u255a",
@@ -150,6 +157,12 @@ struct box_styles UBOXES[] = {{"\u250c", "\u2510", "\u2500", "\u2502", "\u2514",
                               {"\u2552", "\u2555", "\u2550", "\u2502", "\u2558",
                                "\u255b", "\u255e", "\u2561"}};
 
+/**
+ * @brief CP437 box characters
+ *
+ * top-left, top-right, top, side, bottom-left, bottom-right, middle-left,
+ * middle-right See \ref BorderStyle for the order the boxes are in.
+ */
 struct box_styles BOXES[] = {
     /*
             # ┌──┐
@@ -217,6 +230,14 @@ struct box_styles BOXES[] = {
     },
 };
 
+// These already exists in the above structures.  Whoops.
+
+/**
+ * @brief CP437 box line joining data
+ *
+ * SINGLE 0, DOUBLE 1
+ * Join Border to Line, 0 is Left, 1 is Right.
+ */
 const char *JOIN[2][2][2] = {{
                                  {"\xc3", "\xb4"}, // SS 00
                                  {"\xc6", "\xb5"}  // SD 01
@@ -226,6 +247,11 @@ const char *JOIN[2][2][2] = {{
                                  {"\xcc", "\xb9"}, // DD 11
                              }};
 
+/**
+ * @brief Unicode box line joining data
+ * SINGLE 0, DOUBLE 1
+ * Join Border to Line, 0 is Left, 1 is Right.
+ */
 const char *UJOIN[2][2][2] = {{
                                   {"\u251c", "\u2524"}, // SS ├ ┤
                                   {"\u255e", "\u2561"}  // SD ╞ ╡
@@ -352,6 +378,16 @@ std::unique_ptr<Line> Panel::spacer_line(bool single) {
 // operator<< Panel is called to output the Menu.
 // Menu has been massively changed to use Render instead of Colorizer.
 
+/**
+ * @brief Output panel to stream
+ *
+ * This uses the Panel.x, Panel.y to render the panel using ANSI control codes.
+ * Border style is considered, and wether or not we are using unicode.
+ * Colors of the border, and lines use their color or their renderFunction.
+ * @param os
+ * @param p
+ * @return std::ostream&
+ */
 std::ostream &operator<<(std::ostream &os, const Panel &p) {
   if (p.hidden)
     return os;
@@ -561,6 +597,13 @@ Menu::Menu(int x, int y, int width) : Panel(x, y, width) {
   chosen = 0;
 }
 
+/**
+ * @brief Construct a new Menu:: Menu object
+ *
+ * This creates a panel with a default width.
+ * The location needs to be changed \ref Panel::set
+ * @param width
+ */
 Menu::Menu(int width) : Panel(width) {
   setStyle(BorderStyle::DOUBLE);
   setRender(true, defaultSelectedRender);
@@ -870,6 +913,16 @@ void Screen::update(void) {
   }
 }
 
+/**
+ * @brief Outputs screen to stream.
+ * 
+ * This iterates over the panels, and renders them.
+ * See \ref door::Panel
+ * 
+ * @param os 
+ * @param s 
+ * @return std::ostream& 
+ */
 std::ostream &operator<<(std::ostream &os, const Screen &s) {
   // if (!s.hidden) {
   for (auto &panel : s.panels) {

test-door.cpp

@@ -141,7 +141,8 @@ TEST_F(DoorTest, LineOutput) {
   door::Line color("Cat", 4,
                    door::ANSIColor(door::COLOR::BLACK, door::COLOR::WHITE));
   *d << color;
-  EXPECT_STREQ(d->debug_buffer.c_str(), "\x1b[30;47mCat ");
+  EXPECT_STREQ(d->debug_buffer.c_str(), "\x1b[30;47mCat");
+  // EXPECT_STREQ(d->debug_buffer.c_str(), "\x1b[30;47mCat ");
 
   *d << door::reset;
   d->debug_buffer.clear();