Fluid: restructuring and commenting.

tl;dr : making Fluid maintainable, no changes in code execution and logic.

This is a pretty extensive restructuring of the Fluid source tree.
It was neccessary because source and header files were getting
much too big to handle. Many source files had no header, and many
headers declared functions that were in diffrent source files.

Reorganized much of the include statements.
Added comments to some of the files.
Added Doxygen configuration file for standalone Fluid docs.

Tested everything by rebuilding Fluid .fl designs with the resorted
version of Fluid.

1 files changed, 77 insertions, 20 deletions

diff --git a/fluid/CodeEditor.cxx b/fluid/CodeEditor.cxx
index a6bfecc48..773a19000 100644
--- a/fluid/CodeEditor.cxx
+++ b/fluid/CodeEditor.cxx
@@ -19,12 +19,26 @@
 // Include necessary headers...
 //
 
+#include "CodeEditor.h"
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <ctype.h>
-#include "CodeEditor.h"
 
+// ---- CodeEditor implementation
+
+/** \class CodeEditor
+ A widget derived from Fl_Text_Editor that implements C++ code highlighting.
+
+ CodeEditor is used in Fluid whenever the user can edit C++ source
+ code or header text.
+ */
+
+/**
+ Lookup table for all supported styles.
+ Every table entry describes a rendering style for the corresponding text.
+ */
 Fl_Text_Display::Style_Table_Entry CodeEditor::
                 styletable[] = {        // Style table
                   { FL_FOREGROUND_COLOR, FL_COURIER,        11 }, // A - Plain
@@ -37,18 +51,13 @@ Fl_Text_Display::Style_Table_Entry CodeEditor::
                   { 220, /* med cyan */  FL_COURIER,        11 }  // H - Single quote chars
                 };
 
-// attempt to make the fluid code editor widget honour textsize setting
-void CodeEditor::textsize(Fl_Fontsize s) {
-  Fl_Text_Editor::textsize(s); // call base class method
-  // now attempt to update our styletable to honour the new size...
-  int entries = sizeof(styletable) / sizeof(styletable[0]);
-  for(int iter = 0; iter < entries; iter++) {
-    styletable[iter].size = s;
-  }
-} // textsize
-
-
-// 'style_parse()' - Parse text and produce style data.
+/**
+ Parse text and produce style data.
+ \param[in] in_tbuff text buffer to parse
+ \param[inout] in_sbuf style buffer we modify
+ \param[in] in_len byte length to parse
+ \param[in] in_style starting style letter
+ */
 void CodeEditor::style_parse(const char *in_tbuff,         // text buffer to parse
                              char       *in_sbuff,         // style buffer we modify
                              int         in_len,           // byte length to parse
@@ -99,10 +108,19 @@ void CodeEditor::style_parse(const char *in_tbuff,         // text buffer to par
   }
 }
 
-// 'style_unfinished_cb()' - Update unfinished styles.
-void CodeEditor::style_unfinished_cb(int, void*) { }
+/**
+ Update unfinished styles.
+ */
+void CodeEditor::style_unfinished_cb(int, void*) {
+}
 
-// 'style_update()' - Update the style buffer...
+/**
+ Update the style buffer.
+ \param[in] pos insert position in text
+ \param[in] nInserted number of bytes inserted
+ \param[in] nDeleted number of bytes deleted
+ \param[in] cbArg pointer back to the code editr
+ */
 void CodeEditor::style_update(int pos, int nInserted, int nDeleted,
                               int /*nRestyled*/, const char * /*deletedText*/,
                               void *cbArg) {
@@ -150,6 +168,10 @@ void CodeEditor::style_update(int pos, int nInserted, int nDeleted,
   free(style);
 }
 
+/**
+ Find the right indentation depth after pressing the Enter key.
+ \param[in] e pointer back to the code editor
+ */
 int CodeEditor::auto_indent(int, CodeEditor* e) {
   if (e->buffer()->selected()) {
     e->insert_position(e->buffer()->primary_selection()->start());
@@ -183,7 +205,11 @@ int CodeEditor::auto_indent(int, CodeEditor* e) {
   return 1;
 }
 
-// Create a CodeEditor widget...
+/**
+ Create a CodeEditor widget.
+ \param[in] X, Y, W, H position and size of the widget
+ \param[in] L optional label
+ */
 CodeEditor::CodeEditor(int X, int Y, int W, int H, const char *L) :
   Fl_Text_Editor(X, Y, W, H, L) {
   buffer(new Fl_Text_Buffer);
@@ -209,7 +235,9 @@ CodeEditor::CodeEditor(int X, int Y, int W, int H, const char *L) :
                   (Fl_Text_Editor::Key_Func)auto_indent);
 }
 
-// Destroy a CodeEditor widget...
+/**
+ Destroy a CodeEditor widget.
+ */
 CodeEditor::~CodeEditor() {
   Fl_Text_Buffer *buf = mStyleBuffer;
   mStyleBuffer = 0;
@@ -220,7 +248,35 @@ CodeEditor::~CodeEditor() {
   delete buf;
 }
 
+/**
+ Attempt to make the fluid code editor widget honour textsize setting.
+ This works by updating the fontsizes in the style table.
+ \param[in] s the new general height of the text font
+ */
+void CodeEditor::textsize(Fl_Fontsize s) {
+  Fl_Text_Editor::textsize(s); // call base class method
+  // now attempt to update our styletable to honour the new size...
+  int entries = sizeof(styletable) / sizeof(styletable[0]);
+  for(int iter = 0; iter < entries; iter++) {
+    styletable[iter].size = s;
+  }
+} // textsize
+
+// ---- CodeViewer implementation
 
+/** \class CodeViewer
+ A widget derived from CodeEditor with highlighting for code blocks.
+
+ This widget is used by the SourceView system to show the design's
+ source an header code. The secondary highlighting show the text
+ part that corresponds to the selected widget(s).
+ */
+
+/**
+ Create a CodeViewer widget.
+ \param[in] X, Y, W, H position and size of the widget
+ \param[in] L optional label
+ */
 CodeViewer::CodeViewer(int X, int Y, int W, int H, const char *L)
 : CodeEditor(X, Y, W, H, L)
 {
@@ -229,10 +285,11 @@ CodeViewer::CodeViewer(int X, int Y, int W, int H, const char *L)
   cursor_style(CARET_CURSOR);
 }
 
-
+/**
+ Tricking Fl_Text_Display into using bearable colors for this specific task.
+ */
 void CodeViewer::draw()
 {
-  // Tricking Fl_Text_Display into using bearable colors for this specific task
   Fl_Color c = Fl::get_color(FL_SELECTION_COLOR);
   Fl::set_color(FL_SELECTION_COLOR, fl_color_average(FL_BACKGROUND_COLOR, FL_FOREGROUND_COLOR, 0.9f));
   CodeEditor::draw();