Fluid: update comments

fluid/Fluid.cxx

@@ -118,20 +118,31 @@ Application::Application()
 /**
  Start Fluid.
 
- Fluid can run in interactive mode with a full user interface to design new
- user interfaces and write the C++ files to manage them,
+ Fluid supports two execution modes:
+ - Interactive mode: launches the full GUI for editing interfaces and
+   generating C++ code.
+ - Batch mode: runs from the command line and converts .fl files to C++
+   source and header files.
 
- Fluid can run form the command line in batch mode to convert .fl design files
- into C++ source and header files. In batch mode, no display is needed,
- particularly no X11 connection will be attempted on Linux/Unix.
+ Batch mode is headless. On Linux/Unix, Fluid does not attempt to connect
+ to X11.
 
- \param[in] argc number of arguments in the list
- \param[in] argv pointer to an array of arguments
- \return in batch mode, an error code will be returned via \c exit() . This
- function return 1, if there was an error in the parameters list.
- \todo On Windows, Fluid can under certain conditions open a dialog box, even
- in batch mode. Is that intentional? Does it circumvent issues with Windows'
- stderr and stdout?
+ \param[in] argc number of command-line arguments
+ \param[in] argv pointer to the command-line argument array
+ \return in batch mode, status is reported via \c exit(). This function
+ returns 1 only if command-line argument parsing fails.
+
+ On Windows, Fluid is built in two variants:
+ - fluid.exe: GUI variant without console I/O (stdin/stdout).
+ - fluid-cmd.exe: console variant that uses stdin/stdout and can attach to or
+   open a console.
+
+ This split avoids unwanted console windows in GUI workflows while preserving
+ predictable console behavior for scripting and batch runs.
+
+ Application::console_mode() controls how diagnostics are emitted:
+ GUI dialogs or console output. fluid.exe always uses dialogs. fluid-cmd.exe,
+ and all non-Windows builds, choose behavior based on the `batch_mode` flag.
  */
 int Application::run(int argc,char **argv) {
   setlocale(LC_ALL, "");      // enable multi-language errors in file chooser

fluid/app/shell_command.cxx

@@ -350,11 +350,6 @@ static void expand_macros(std::string &cmd) {
   expand_macro(cmd, "@HEADERFILE_NAME@",  Fluid.proj.headerfile_name());
   expand_macro(cmd, "@TEXTFILE_PATH@",    Fluid.proj.stringsfile_path());
   expand_macro(cmd, "@TEXTFILE_NAME@",    Fluid.proj.stringsfile_name());
-//  TODO: implement finding the script `fltk-config` for all platforms
-//  if (cmd.find("@FLTK_CONFIG@") != std::string::npos) {
-//    find_fltk_config();
-//    expand_macro(cmd, "@FLTK_CONFIG@",      fltk_config_cmd.c_str());
-//  }
   if (cmd.find("@TMPDIR@") != std::string::npos)
     expand_macro(cmd, "@TMPDIR@",           Fluid.get_tmpdir());
 }

fluid/io/Code_Writer.cxx

@@ -471,7 +471,7 @@ void Code_Writer::write_c_indented(const std::string& codeblock, int additional_
  constructor whereas functions, declarations, and inline data are seen as
  members of the class itself.
  */
-bool is_class_member(Node *t) {
+bool is_direct_class_member(Node *t) {
   return    dynamic_cast<Function_Node*>(t)
          || dynamic_cast<Decl_Node*>(t)
          || dynamic_cast<Data_Node*>(t)
@@ -491,13 +491,13 @@ bool is_class_member(Node *t) {
  \param[in] q should be a comment type
  \return true if this comment is followed by a class member
  \return false if it is followed by a widget or code
- \see is_class_member(Node *t)
+ \see is_direct_class_member(Node *t)
  */
 static bool is_comment_before_class_member(Node *q) {
   if (dynamic_cast<Comment_Node*>(q) && q->next && q->next->level==q->level) {
     if (dynamic_cast<Comment_Node*>(q->next))
       return is_comment_before_class_member(q->next);
-    if (is_class_member(q->next))
+    if (is_direct_class_member(q->next))
       return true;
   }
   return false;
@@ -547,10 +547,11 @@ Node* Code_Writer::write_code(Node* p) {
     // instead of inside a constructor. So below we have to treat all children
     // that  are widgets in write_code1(), and all children that are regular
     // class members (Methods, Variables) *after* write_code2().
-    // \todo Widgets should be required to be in a constructor
+    // \todo Improve the concept of Widget_Class_Node to be more like a regular
+    //       class, with a constructor
     for (q = p->next; q && q->level > p->level;) {
       // note: maybe declaration blocks should be handled like comments in the context
-      if (!is_class_member(q) && !is_comment_before_class_member(q)) {
+      if (!is_direct_class_member(q) && !is_comment_before_class_member(q)) {
         q = write_code(q);
       } else {
         int level = q->level;
@@ -566,7 +567,7 @@ Node* Code_Writer::write_code(Node* p) {
     mark_end(p->finalize_node);
 
     for (q = p->next; q && q->level > p->level;) {
-      if (is_class_member(q) || is_comment_before_class_member(q)) {
+      if (is_direct_class_member(q) || is_comment_before_class_member(q)) {
         q = write_code(q);
       } else {
         int level = q->level;

fluid/nodes/factory.cxx

@@ -15,28 +15,20 @@
 //
 
 /**
+ This file implements the FLUID node factory for built-in widget types.
 
+ It defines prototype instances for most widget node classes and the lookup
+ tables used to map type names to those prototypes.
 
- \todo Verify the text
-
- Type classes for most of the fltk widgets.  Most of the work
- is done by code in Widget_Node.cxx.  Also a factory instance
- of each of these type classes.
-
- This file also contains the "new" menu, which has a pointer
- to a factory instance for every class (both the ones defined
- here and ones in other files)
-
-
- Type classes for most of the fltk widgets.  Most of the work
- is done by code in Widget_Node.C.  Also a factory instance
- of each of these type classes.
-
- This file also contains the "new" menu, which has a pointer
- to a factory instance for every class (both the ones defined
- here and ones in other files)
+ Most shared widget-node behavior is implemented in Widget_Node.cxx and in
+ specialized node files (for example Button_Node.cxx, Group_Node.cxx, and
+ Window_Node.cxx).
 
+ This file also defines the *New* menu model. Each menu entry stores a pointer
+ to a node prototype, including prototypes defined here and in other
+ translation units.
  */
+
 #include "nodes/factory.h"
 
 #include "app/Snap_Action.h"

fluid/proj/mergeback.cxx

@@ -44,9 +44,6 @@ using namespace fluid::proj;
 //        [] check mergeback when loading project
 //        [] check mergeback when app gets focus
 //          [] always apply if safe
-// TODO: command line option for mergeback
-//        -mb or --merge-back
-//        -mbs or --merge-back-if-safe
 // NOTE: automatic mergeback on timer when file changes if app focus doesn't work
 // NOTE: allow the user to edit comment blocks
 
@@ -741,7 +738,7 @@ int mergeback_code_files(Project &proj, Mergeback::Feedback feedback)
     // Fluid may have written the source code elsewhere (e.g. in a CMake setup).
     // Fluid tries to keep track of the last write location of a source file
     // matching a project, and uses that location instead.
-    // TODO: this is not working as expected yet.
+    // TODO: Verify that this works in all common cases
     Fl_Preferences build_records(Fl_Preferences::USER_L, "fltk.org", "fluid-build");
     Fl_Preferences path(build_records, project_filename.c_str());
     int i, n = (int)project_filename.size();

fluid/widgets/Node_Browser.cxx

@@ -213,7 +213,7 @@ static char *copy_trunc(char *p, const char *str, int maxl, int quote, int trunc
  \param[in] X, Y, W, H position and size of widget
  \param[in] l optional label
  \todo It would be nice to be able to grab one or more nodes and move them
-    within the hierarchy.
+    within the hierarchy via drag'n'drop.
  */
 Node_Browser::Node_Browser(int X,int Y,int W,int H,const char*l) :
   Fl_Browser_(X,Y,W,H,l)
@@ -253,7 +253,6 @@ void *Node_Browser::item_prev(void *l) const {
  Override the method to check if an item was selected.
  \param l this item
  \return 1 if selected, 0 if not
- \todo what is the difference between selected and selected, and why do we do this?
  */
 int Node_Browser::item_selected(void *l) const {
   return ((Node*)l)->selected;