Fluid documentation

[melcher....@googlemail.com]

Since I was going through every function of Fluid anyway in an attempt to improve the developer documentation, I tried to write some user doc while I am at it.

Please take a look at: 

http://messagepad.org/fluid/code.html

and let me know what you think (this is really only a single chapter so far, generated with doxygen in the fluid folder).

It's funny to discover built-in trickery that AFAIK was never documented. For example, I did not know that leaving the Name in a Function node empty will create a main() function that opens the window inside and calls Fl::run().

The git push was somewhat accidental. In the future, I would prefer to update the linked site and collect all documentation changes in a branch.

Again, any comments are welcome.

 - Matthias

[Ian MacArthur]

On 9 Dec 2021, at 17:36, Matt wrote:
>
>
> It's funny to discover built-in trickery that AFAIK was never documented. For example, I did not know that leaving the Name in a Function node empty will create a main() function that opens the window inside and calls Fl::run().

Yes - fluid has “always" done that; indeed the “Function/Method Properties” dialog even says as much... It’s handy of you are throwing together a quick test hack...

[melcher....@googlemail.com]

If anyone is following this, docs are now in a branch inside my cloned GitHub repo: https://github.com/MatthiasWM/fltk/commits/fluid_docs .

imacarthur schrieb am Donnerstag, 9. Dezember 2021 um 20:18:16 UTC+1:

> It's funny to discover built-in trickery that AFAIK was never documented. For example, I did not know that leaving the Name in a Function node empty will create a main() function that opens the window inside and calls Fl::run().

Yes - fluid has “always" done that; indeed the “Function/Method Properties” dialog even says as much... It’s handy of you are throwing together a quick test hack...

You are right, bad example. A different one: If a Declaration node is inside a Class node, Fluid recognises the keywords class, struct, typedef, and FL_EXPORT at the start of the declaration and copies those declarations verbatim to the header file. Otherwise, Fluid will remove all but one spaces between the declaration and a potential inline comment ( `int x=1;       // test` will become `int x=1; // test`).

If anyone can explain that to, that would be quite helpful.

[Greg Ercolano]

On 12/11/21 5:53 AM, 'melcher....@googlemail.com' via fltk.coredev wrote:

You are right, bad example. A different one: If a Declaration node is inside a Class node, Fluid recognises the keywords class, struct, typedef, and FL_EXPORT at the start of the declaration and copies those declarations verbatim to the header file. Otherwise, Fluid will remove all but one spaces between the declaration and a potential inline comment ( `int x=1;       // test` will become `int x=1; // test`).

If anyone can explain that to, that would be quite helpful.

    I'm not looking at the code and not even familiar with it, but I'm guessing it tries
    to remove trailing spaces from the user's declaration code (thinking trailing white is an error),
    but tacks on a trailing space just to make sure comments don't "touch" the code statement,
    so as to avoid 'int x=1;// test'.

    I actually saw github's "diff" error-highlighted comments touching code recently, it was something like:

        void somefunc(int */*xyz*/, ..)

    ..I thought this an interesting trend, and even saw similar warnings from one of the newer
    compilers which warned about possibly confusing indenting..! Everything's getting very
    picky these days (which is probably a good thing). I personally never liked the idea of comments
    being too close to code, as it can be confused for a math formula or similar.

[Greg Ercolano]

On 12/9/21 9:36 AM, 'melcher....@googlemail.com' via fltk.coredev wrote:

Since I was going through every function of Fluid anyway in an attempt to improve the developer documentation, I tried to write some user doc while I am at it.

    Just catching up with this thread as I'm curious, and looking to be inspired.

Please take a look at:

http://messagepad.org/fluid/code.html

and let me know what you think (this is really only a single chapter so far, generated with doxygen in the fluid folder).

    Um, I just tried that link and I got what looks like a hijacked website.
    Is that really the correct link?

    Or are "Hernia Mesh Lawsuits" and "Psoriatic Arthritis"
    new features in fluid? :D  No, but seriously, wat the heck:

[Greg Ercolano]

Also, I noticed there's now very cool looking doxygen style commenting
in the fluid source code now, which is awesome.

Should I be able to see that in the doxygen docs somehow, perhaps something
separate from the usual '( cd documentation; make html)'? I wasn't sure how
to generate those docs or where to find them.

[Albrecht Schlosser]

On 12/15/21 12:00 AM Greg Ercolano wrote:
>
> Also, I noticed there's now very cool looking doxygen style commenting
> in the fluid source code now, which is awesome.
>

Yeah, great work of Matthias.

> Should I be able to see that in the doxygen docs somehow, perhaps
> something
> separate from the usual '( cd documentation; make html)'? I wasn't
> sure how
> to generate those docs or where to find them.
>

$ cd fluid
$ doxygen

Documentation is generated in fluid/documentation/html [ /index.html as
usual entry page ]

Doxygen versions lower then 1.9.1 may likely issue some warnings which
can be ignored.

[Greg Ercolano]

    Ah, thanks.. interesting!

    Comparing my old code comments to doxygen for the ExternalCodeEditor class..
    Interesting to see it reformatted, e.g. "before" (fltk 1.3.x):

---

}

// [Protected] Start editor in background (fork/exec)
// Returns:
//    >  0 on success, leaves editor child process running as 'pid_'
//    > -1 on error, posts dialog with reason (child exits)
//
int ExternalCodeEditor::start_editor(const char *editor_cmd,
                                     const char *filename) {

---

    ..and "after" (fltk 1.4.x):

---

}

/**
 Start editor in background (fork/exec)
 \return 0 on success, leaves editor child process running as 'pid_'
 \return -1 on error, posts dialog with reason (child exits)
 */
int ExternalCodeEditor::start_editor(const char *editor_cmd,
                                     const char *filename) {

---

    Looks good!

[melcher....@googlemail.com]

Meh, I changed to name of that page: http://messagepad.org/fluid/codeNodes.html . My provider sells pages with typos, as you found out :-/

[Greg Ercolano]

On 12/15/21 11:36 AM, 'melcher....@googlemail.com' via fltk.coredev wrote:

Meh, I changed to name of that page: http://messagepad.org/fluid/codeNodes.html .

My provider sells pages with typos, as you found out :-/

    Oh man, that's evil.

    I can help you setup a linode server if you want. $5/mo with auto-billing,
    and you get your own unix box with root and everything. Flexible disk.