STR 3210: fixing indentation of Fl_Menu_Item cnd Widget allbacks.

also added and fixed a few comments

STR 3210: fixed indenting of widget callbacks.

Also fixed what is considered a 'name' (could still be improved).
Also better formatting inlined functions in the header.

fluid/CodeEditor.cxx

@@ -54,7 +54,7 @@ Fl_Text_Display::Style_Table_Entry CodeEditor::
 /**
  Parse text and produce style data.
  \param[in] in_tbuff text buffer to parse
- \param[inout] in_sbuf style buffer we modify
+ \param[inout] in_sbuff style buffer we modify
  \param[in] in_len byte length to parse
  \param[in] in_style starting style letter
  */

fluid/Fl_Function_Type.cxx

@@ -405,7 +405,11 @@ void Fl_Function_Type::write_code1() {
       }
       *sptr = '\0';
 
-      write_h("%s;\n", s);
+      if (s[strlen(s)-1] == '}') {  // special case for inlined functions
+        write_h("%s\n", s);
+      } else {
+        write_h("%s;\n", s);
+      }
       // skip all function default param. init in body:
       int skips=0,skipc=0;
       int nc=0,plevel=0;

fluid/Fl_Menu_Type.cxx

@@ -208,7 +208,8 @@ void Fl_Menu_Item_Type::write_static() {
     const char* ut = user_data_type() ? user_data_type() : "void*";
     write_c(", %s", ut);
     if (use_v) write_c(" v");
-    write_c(") {\n  %s", callback());
+    write_c(") {\n");
+    write_c_indented(callback());
     if (*(d-1) != ';') {
       const char *p = strrchr(callback(), '\n');
       if (p) p ++;

fluid/Fl_Type.cxx

@@ -315,12 +315,12 @@ void Fl_Type::add(Fl_Type *p) {
 /**
  Add this list/tree of widgets as a new sibling before p.
 
- \c this is not part of the widget browser. \c p should be in the
+ \c this is not part of the widget browser. \c g should be in the
  widget_browser, so \c Fl_Type::first and \c Fl_Type::last are valid for \c p.
 
  This methods updates the widget_browser.
 
- \param[in] p insert \c this tree as a child of \c p
+ \param[in] g insert \c this tree as a child of \c p
  */
 void Fl_Type::insert(Fl_Type *g) {
   // p is not in the Widget_Browser, so we must run the linked list to find the last entry
@@ -445,7 +445,7 @@ void Fl_Type::open() {
 
 /**
  Move this node (and its children) into list before g.
- \param[in] p move \c this tree before \c p
+ \param[in] g move \c this tree before \c g
  */
 void Fl_Type::move_before(Fl_Type* g) {
   if (level != g->level) printf("move_before levels don't match! %d %d\n",

fluid/Fl_Widget_Type.cxx

@@ -1952,7 +1952,8 @@ void selection_changed(Fl_Type *p) {
 
 // test to see if user named a function, or typed in code:
 int is_name(const char *c) {
-  for (; *c; c++) if (ispunct(*c) && *c!='_' && *c!=':') return 0;
+  for (; *c; c++)
+    if ((ispunct(*c)||*c=='\n') && *c!='_' && *c!=':') return 0;
   return 1;
 }
 
@@ -2052,7 +2053,8 @@ void Fl_Widget_Type::write_static() {
     const char* ut = user_data_type() ? user_data_type() : "void*";
     write_c(", %s", ut);
     if (use_v) write_c(" v");
-    write_c(") {\n  %s", callback());
+    write_c(") {\n");
+    write_c_indented(callback());
     if (*(d-1) != ';') {
       const char *p = strrchr(callback(), '\n');
       if (p) p ++;

fluid/code.cxx

@@ -137,6 +137,10 @@ included::~included() {
 }
 static included *included_root;
 
+/**
+ Print a formatted line to the header file, unless the same line was produced before.
+ \param[in] format printf-style formatting text, followed by a vararg list
+ */
 int write_declare(const char *format, ...) {
   va_list args;
   char buf[1024];
@@ -164,7 +168,20 @@ int varused_test;
 int varused;
 
 /**
- Write an array of C characters (adds a null).
+ Write a C string to the code file, escaping non-ASCII characters.
+
+ Adds " before and after the text.
+
+ A list of control characters and ", ', and \\ are escaped by adding a \\ in
+ front of them. Escape ?? by wrinting ?\\?. All other characters that are not
+ between 32 and 126 inclusive will be escaped as octal characters.
+
+ This function is utf8 agnostic.
+
+ \param[in] s write this string
+ \param[in] length write so many bytes in this string
+
+ \see write_cstring(const char*)
  */
 void write_cstring(const char *s, int length) {
   if (varused_test) {
@@ -249,12 +266,18 @@ void write_cstring(const char *s, int length) {
 }
 
 /**
- Write a C string, quoting characters if necessary.
+ Write a C string, escaping non-ASCII characters.
+ \param[in] s write this string
+ \see write_cstring(const char*, int)
  */
-void write_cstring(const char *s) {write_cstring(s, (int)strlen(s));}
+void write_cstring(const char *s) {
+  write_cstring(s, (int)strlen(s));
+}
 
 /**
  Write an array of C binary data (does not add a null).
+ The output is bracketed in { and }. The content is written
+ as decimal bytes, i.e. `{ 1, 2, 200 }`
  */
 void write_cdata(const char *s, int length) {
   if (varused_test) {
@@ -289,7 +312,11 @@ void write_cdata(const char *s, int length) {
   putc('}', code_file);
 }
 
-// TODO: document me
+/**
+ Print a formatted line to the source file.
+ \param[in] format printf-style formatting text
+ \param[in] arg list of arguments
+ */
 void vwrite_c(const char* format, va_list args) {
   if (varused_test) {
     varused = 1;
@@ -298,7 +325,10 @@ void vwrite_c(const char* format, va_list args) {
   vfprintf(code_file, format, args);
 }
 
-// TODO: document me
+/**
+ Print a formatted line to the source file.
+ \param[in] format printf-style formatting text, followed by a vararg list
+ */
 void write_c(const char* format,...) {
   va_list args;
   va_start(args, format);
@@ -316,7 +346,10 @@ void write_cc(const char *indent, int n, const char *c, const char *com) {
     write_c("%s%.*s;\n", indent, n, c);
 }
 
-// TODO: document me
+/**
+ Print a formatted line to the header file.
+ \param[in] format printf-style formatting text, followed by a vararg list
+ */
 void write_h(const char* format,...) {
   if (varused_test) return;
   va_list args;
@@ -335,6 +368,25 @@ void write_hc(const char *indent, int n, const char* c, const char *com) {
     write_h("%s%.*s;\n", indent, n, c);
 }
 
+/**
+ Write one or more lines of code, indenting each one of them.
+ \param[in] textlines one or more lines of text, seperated by \\n
+ */
+void write_c_indented(const char *textlines) {
+  if (textlines) {
+    indentation+=2;
+    for (;;) {
+      const char *newline = strchr(textlines, '\n');
+      if (!newline) break;
+      write_c("%s%.*s\n", indent(), (int)(newline-textlines), textlines);
+      textlines = newline+1;
+    }
+    if (*textlines)
+      write_c("%s%s", indent(), textlines);
+    indentation-=2;
+  }
+}
+
 
 /**
  Recursively dump code, putting children between the two parts of the parent code.

fluid/code.h

@@ -37,6 +37,7 @@ void write_c(const char*, ...) __fl_attr((__format__ (__printf__, 1, 2)));
 void write_cc(const char *, int, const char*, const char*);
 void write_h(const char*, ...) __fl_attr((__format__ (__printf__, 1, 2)));
 void write_hc(const char *, int, const char*, const char*);
+void write_c_indented(const char *textlines);
 int write_code(const char *cfile, const char *hfile);
 int write_strings(const char *sfile);
 void write_public(int state); // writes pubic:/private: as needed

fluid/documentation/src/code.dox

@@ -2,9 +2,9 @@
 
 /**
 
- \page code Code Nodes
+\page codeNodes Code Nodes
 
- Overview of code nodes.
+Overview of code nodes.
 
 
 \section function Functions and Methods
@@ -153,9 +153,24 @@ is no text after the keyword.
 
 ### Further Options ###
 
+Users can define a comment text in the *comment* field. The first line of the
+comment will be shown in the widget browser. The comment text will be generated
+in the source file ahead of thefunction.
+```
+// .cxx
+/*
+ My multilen comment
+ will be here
+ */
+Fl_Window* make_window() {
+```
+
 Fluid recognizes default values in the argument list and geneartes them in the
 declaration, but omits them in the implementation.
 
+A short function body can be appended in the *Name* field. With no child, this
+creates an inlined function in the header file.
+
 <!-- ----------------------------------------------------------------------- -->
 
 \section code C Source Code

fluid/file.cxx

@@ -125,9 +125,9 @@ void write_word(const char *w) {
 }
 
 /**
- Write an arbitrary formatted word to the .fl file, or a comment, etc. .
+ Write an arbitrary formatted word to the .fl file, or a comment, etc .
  If needspace is set, then one space is written before the string
- unless the format starts with a newline character '\\n'.
+ unless the format starts with a newline character \\n.
  */
 void write_string(const char *format, ...) {
   va_list args;
@@ -229,9 +229,9 @@ static int hexdigit(int x) {
 }
 
 /**
- Convert an ASCII sequence form the .fl file that starts with a \\ into a single character.
- Conversion includes the common C style \\ characters like \\n, \x## hex
- values, and \o### octal values.
+ Convert an ASCII sequence form the \.fl file that starts with a \\ into a single character.
+ Conversion includes the common C style \\ characters like \\n, \\x## hex
+ values, and \\o### octal values.
  */
 static int read_quoted() {      // read whatever character is after a \ .
   int c,d,x;

fluid/widget_browser.cxx

@@ -72,7 +72,7 @@ void redraw_widget_browser(Fl_Type *caller)
 /**
  Select or deselect a node in the widget browser.
  \param[in] o (de)select this node
- \oaram[in] v the new selection state (1=select, 0=de-select)
+ \param[in] v the new selection state (1=select, 0=de-select)
  */
 void select(Fl_Type *o, int v) {
   widget_browser->select(o,v,1);
@@ -130,7 +130,7 @@ void reveal_in_browser(Fl_Type *t) {
  \param[in] str copy this string; utf8 aware
  \param[in] maxl maximum number of letter to copy until we print
     the elipsis (...)
- \param[in] auote if set, the resulting string is embedded in double quotes
+ \param[in] quote if set, the resulting string is embedded in double quotes
  \returns pointer to end of string (before terminating null byte).
  \note the buffer p must be large enough to hold (4 * (maxl+1) + 1) bytes
     or (4 * (maxl+1) + 3) bytes if quoted, e.g. "123..." because each UTF-8
@@ -384,7 +384,7 @@ void Widget_Browser::item_draw(void *v, int X, int Y, int, int) const {
 
 /**
  Override the method to return the width of an item representation in Flixels.
- \param l this item
+ \param v this item
  \return width in FLTK units
  */
 int Widget_Browser::item_width(void *v) const {