Fluid: sample documentation, please check http://messagepad.org/fluid/code.html

4 files changed, 156 insertions, 9 deletions

diff --git a/fluid/documentation/src/code.dox b/fluid/documentation/src/code.dox
index 58b041d11..d07420dce 100644
--- a/fluid/documentation/src/code.dox
+++ b/fluid/documentation/src/code.dox
@@ -6,15 +6,163 @@
 
  Overview of code nodes.
 
- \section function Functions and Methods
 
- Creating functions and methods.
-
- \code
- #include "test.fl"
- \endcode
-
- \section code Code
+\section function Functions and Methods
+
+![](flFunction.png) Functions
+
+Fluid can generate C functions, C++ functions, and methods in classes.
+Functions can contain widgets to build windows and dialogs. *Code* nodes can
+be used to add more source code to a function.
+
+### Parents ###
+To generate a function, the function node must be created at the top level or
+inside a declaration block. If added inside a class node, this node generates
+a method inside that class.
+
+### Children ###
+Function nodes can contain code nodes and widget trees. The topmost node of a
+widget tree must be a window.
+If the function node has no children, only a forward declaration will be
+created in the header, but no source code will be generated.
+
+\image html flFunctionDialog.png "Function/Method Properties"
+\image latex flFunctionDialog.png "Function/Method Properties"
+
+## Declaring a Function ##
+
+A function node at the top level or inside a declaration block generates a C
+or C++ function.
+
+The *Name* field  contains the function name and all arguments.
+If the *Name* field is left empty, Fluid will generate a typical 'main()' function.
+```
+// .cxx
+int main(int argc, char **argv) {
+  /* code generated by children */
+  w->show(argc, argv); /* <-- code generated if function has a child widget */
+  Fl::run();
+}
+```
+
+If a function node has a name but no children, a forward declaration is
+generated in the header, but the implementation in the source file is omited.
+This is used to reference functions in other modules.
+```
+// .h
+void make_window();
+```
+
+If the function contains one or more Code nodes, an implementation will also be
+generated. The default return type is `void`. Text in the *Return Type* field
+overrides the default type.
+```
+// .cxx
+void make_window() {
+  /* code generated by children */
+}
+```
+
+If the function contains a widget, a pointer to the first widget
+will be created. The default return type will match the type of the
+first widget, and a pointer to the widget will be returned.
+```
+// .h
+Fl_Window* make_window();
+```
+
+```
+// .cxx
+Fl_Window* make_window() {
+  Fl_Window* w;
+  /* code generated by children:
+   * w = new Fl_Window(...)
+   */
+  return w;
+}
+```
+
+### Options for Functions ###
+
+Choosing *static* in the pulldown menu will declare the function `static` in the
+source file. No prototype will be generated in the header.
+```
+// .cxx
+static Fl_Window* make_window() { ...
+```
+
+If the *C* option is checked, the function will be declared as a plain C
+function in the header file.
+The options *local* and *C* together are not supported.
+```
+// .h
+extern "C" { void my_plain_c_function(); }
+```
+
+## Declaring a Method ##
+
+A function node inside a class node generates a C++ method. If a method node has
+no children, the declaration is generated in the header, but no implementation
+in the source file.
+```
+// .h
+class UserInterface {
+public:
+  void make_window();
+};
+```
+
+If the method contains one or more Code nodes, an implementation will also be
+generated.
+
+```
+// .cxx
+void UserInterface::make_window() {
+  printf("Hello, World!\n");
+}
+```
+
+If the method contains at least on widget, a pointer to the topmost widget
+will be returned and the return type will be generated accordingly.
+```
+// .h
+class UserInterface {
+public:
+  Fl_Double_Window* make_window();
+};
+```
+
+```
+// .cxx
+Fl_Double_Window* UserInterface::make_window() {
+  Fl_Double_Window* w;
+  /* code generated by children */
+  return w;
+}
+```
+
+### Options for Methods ###
+
+Class access can be defined with the pulldown menu. It provides a choice of
+`private`, `protected`, and `public`.
+
+Fluid recognizes the keyword `static` or `virtual` at the beginning of the
+*return type* and will generate the declaration including the keyword, but will
+omit it in the implementation. The return type defaults still apply if there
+is no text after the keyword.
+
+### Further Options ###
+
+Fluid recognizes default values in the argument list and geneartes them in the
+declaration, but omits them in the implementation.
+
+<!-- ----------------------------------------------------------------------- -->
+
+\section code C Source Code
+
+![](flCode.png) Code
+
+...write me.
 
  \section codeblock Code Block
 
@@ -24,7 +172,6 @@
 
  \section class Classes
 
- Fluid can create a new C++ class.
 
  \section widgetclass Widget Class
 
diff --git a/fluid/documentation/src/flCode.png b/fluid/documentation/src/flCode.png
new file mode 100644
index 000000000..a45ece9d3
--- /dev/null
+++ b/fluid/documentation/src/flCode.png
diff --git a/fluid/documentation/src/flFunction.png b/fluid/documentation/src/flFunction.png
new file mode 100644
index 000000000..3cf7a7b3a
--- /dev/null
+++ b/fluid/documentation/src/flFunction.png
diff --git a/fluid/documentation/src/flFunctionDialog.png b/fluid/documentation/src/flFunctionDialog.png
new file mode 100644
index 000000000..bc3d90fb4
--- /dev/null
+++ b/fluid/documentation/src/flFunctionDialog.png