fl_arc() doc improvement?

[Greg Ercolano]

So this issue came up on fltk.discussions regarding the use of fl_arc(), where three people including myself were probably more confused than we should have been about why one of the two forms of the fl_arc() functions wasn't drawing at all.

After solving, I offered the confusion could be avoided by a small clarification in the documentation (red highlighted paragraphs below):

Normally I would just make the change, but fl_arc() is not a function I use much, and wanted to make sure in clarifying, I wasn't missing some other details or drawing contexts, as I think some of you other developers are more familiar with the internals of this than I am.

So I'm asking if I missed anything or if there's better wording needed.

Oh, and the above as a diff:

--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -634,6 +634,18 @@ inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, doub
 /**
   Add a series of points to the current path on the arc of a circle.
 
+  Unlike the integer-coordinate \c fl_arc(x,y,w,h,a1,a2) overload, this
+  function is not a standalone drawing operation. It must be bracketed by
+  matching fl_begin_*() and fl_end_*() calls. Valid path types are
+  \c points, \c line, \c loop, \c polygon, and \c complex_polygon.
+
+  So for example to draw an arc as a line, use fl_begin_line() and fl_end_line() around fl_arc():
+  \code
+      // Draw a 180 degree arc as a line
+      fl_begin_line();
+      fl_arc(200.0, 100.0, 50.0, 0.0, 180.0);
+      fl_end_line();
+  \endcode
   The arc is drawn counter-clockwise from 3 o'clock. If \p end is less than
   \p start then it draws the arc in a clockwise direction. To draw an arc across
   the 3 o'clock line, \p start and \p end can be greater than 360 or less than 0.
@@ -665,6 +677,12 @@ inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, doub
     fl_arc(300.0, 100.0, 50.0, 0.0, 180.0);
     fl_end_polygon();
   \endcode
+
+  \see fl_begin_points(),
+       fl_begin_line(),
+       fl_begin_loop(),
+       fl_begin_polygon(),
+       fl_begin_complex_polygon()
 */
 inline void fl_arc(double x, double y, double r, double start, double end) {
   fl_graphics_driver->arc(x, y, r, start, end);

I think there's another section as well in the "drawing with fltk" where this info might be duplicated, and thus a similar change done there as well.

[Manolo]

The fact the issue arose in fltk.discussion is proof that the reference to the "current path" present in the function's one-line description is not enough. I would suggest to slightly rephrase the first two sentences of the added text as follows to connect it to the "current path":

    Unlike the integer-coordinate \c fl_arc(x,y,w,h,a1,a2) overload, this function requires a current path, that is, 

    it must be bracketed by matching fl_begin_*() and fl_end_*() calls.

[Albrecht Schlosser]

On 8/29/26 03:57 Greg Ercolano wrote:

So this issue came up on fltk.discussions regarding the use of fl_arc(), where three people including myself were probably more confused than we should have been about why one of the two forms of the fl_arc() functions wasn't drawing at all.

After solving, I offered the confusion could be avoided by a small clarification in the documentation (red highlighted paragraphs below):

Normally I would just make the change, but fl_arc() is not a function I use much, and wanted to make sure in clarifying, I wasn't missing some other details or drawing contexts, as I think some of you other developers are more familiar with the internals of this than I am.

I'm generally fine with the suggested changes, and I would also add what Manolo proposed to clarify it even more.

However, I'm not sure if "Valid path types are \c points, \c line, \c loop, \c polygon, and \c complex_polygon" is correct in this context. Can all these path types be combined with arcs ? I'm leaving this open for now.

Another point for better documentation experience (doxygen related): I would change

  "Unlike the integer-coordinate \c fl_arc(x,y,w,h,a1,a2) overload"

to
  "Unlike the integer-coordinate fl_arc(int, int, int, int, double, double) overload".

Note: remove "\c" and let doxygen's auto-link feature create a link to the docs of that integer-coordinate function (tested, works well, see screenshot below).

Furthermore, the given example is superfluous, because there are already examples below the image.

My suggestion would therefore be:
```diff

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index e936de5ab..a13814a0e 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -634,6 +634,13 @@ inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, doub
 /**
   Add a series of points to the current path on the arc of a circle.
 
+  Unlike the fl_arc(int, int, int, int, double, double) overload that uses
+  integer coordinates, this function is not a standalone drawing operation.
+  It requires an active path; that is, it must be enclosed by corresponding calls
+  to `fl_begin_*()` and `fl_end_*()`.
+  Valid path types are \c points, \c line, \c loop, \c polygon, and \c complex_polygon.
+  See examples below.
+
   The arc is drawn counter-clockwise from 3 o'clock. If \p end is less than
   \p start then it draws the arc in a clockwise direction. To draw an arc across
   the 3 o'clock line, \p start and \p end can be greater than 360 or less than 0.

```

Note: I used google translate to translate the text to German and back to English for better wording than my own. Feel free to improve this.

I think there's another section as well in the "drawing with fltk" where this info might be duplicated, and thus a similar change done there as well.

I'm not a friend of duplicating the same information "everywhere". My general suggestion to change the docs would be to enhance the chapter "Drawing Things in FLTK" with all required information (and examples?) and to refer to this wherever needed so the docs in the code can be shorter (like a reference manual should be) but link to the detailed info for users that need it. However, this is more like a long-term solution than a quick fix.

Screenshot (note the generated link to the integer version):




s/corresponding/matching/ if you like. ;-)

[Greg Ercolano]

    Sounds good to me; shorter is better.

On 8/29/26 08:35, 'Albrecht Schlosser' via fltk.coredev wrote:

I'm generally fine with the suggested changes, and I would also add what Manolo proposed to clarify it even more.

    Yep, agreed..

However, I'm not sure if "Valid path types are \c points, \c line, \c loop, \c polygon, and \c complex_polygon" is correct in this context. Can all these path types be combined with arcs ? I'm leaving this open for now.

    Pretty sure that's the case. I just wasn't sure if there were other cases; I don't know much about "paths" in this context, but I assume it's like opengl meshes and such.

Another point for better documentation experience (doxygen related): I would change
  "Unlike the integer-coordinate \c fl_arc(x,y,w,h,a1,a2) overload"
to
  "Unlike the integer-coordinate fl_arc(int, int, int, int, double, double) overload".

    Ya, I started with that fl_arc(int, int, int, int, double, double) because it makes an accurate link, but it seemed so long as to be confusing; easy for someone to miss that one extra 'int'.. also that many unnamed types would visually overwhelm the average reader, and adding actual names would just make it even longer.

    I figure the first few paragraphs of docs for a function/method shouldn't get too far into the weeds right away.

    I was wondering if there was a way to make a \ref so that I could just say "fl_arc()" and the ref would point it at the right actual function docs, just for brevety.

    Anyway, curious if a \ref (or whatever it's called) might be a better solution to avoid the int,int,int,int..

Furthermore, the given example is superfluous, because there are already examples below the image.

    Ya, again, I did that for clarity, because I think people might not read below the diagram where the examples are. I know I missed it just trying to quick review to answer that discussion, and I stopped at the diagram because I knew that stuff, and didn't look below it.

     I guess I could move the examples up above the diagram, to avoid the redundancy.

I'm not a friend of duplicating the same information "everywhere". [regarding the "drawing with fltk"duplication]

    Yeah, I'm not either, but I figure that's a rewrite of the entire "drawing with fltk" section, a bigger issue.

    I assume it's that way to make the intro into drawing easier to understand, so the user doesn't have to jump around in the docs. (One annoying thing about doxygen is if you click on a link to another doc, then try to return to where you were with the browser's Back button, you don't always end up where you were..! I find I have to middle-click to open new tabs so I don't loose my place)

    To redo the doxygen docs, perhaps there's an \include technique of some kind so the docs from elsewhere get pulled in to that same location, avoiding duplicate docs.

[Albrecht Schlosser]

On 8/29/26 18:06 Greg Ercolano wrote:

    To redo the doxygen docs, perhaps there's an \include technique of some kind so the docs from elsewhere get pulled in to that same location, avoiding duplicate docs.

Yep, there is (for instance) `\include{doc}` which we already use, but IIRC that requires an entire file to be included.

documentation/src/index.dox:11:    <B>FLTK \include{doc} version.dox Programming Manual</B>
documentation/src/index.dox:16:    \include{doc} copyright.dox
documentation/src/preface.dox:6:\include{doc} version.dox,
documentation/src/preface.dox:83:FLTK is \include{doc} copyright.dox

The included files copyright.dox and version.dox are tiny fragments generated by CMake for exactly this usage.
Example:

$ cat documentation/copyright.dox.in
Copyright © 1998 - @YEAR@ by Bill Spitzak and others.

This is to avoid having to edit certain files at every turn of the year.

If we wanted to include some documentation details in more than one place, then we'd have to add one file for each piece of docs (AFAICT). That doesn't make it easier to maintain.

[Greg Ercolano]

On 8/29/26 09:32, 'Albrecht Schlosser' via fltk.coredev wrote:

On 8/29/26 18:06 Greg Ercolano wrote:

    To redo the doxygen docs, perhaps there's an \include technique of some kind so the docs from elsewhere get pulled in to that same location, avoiding duplicate docs.

Yep, there is (for instance) `\include{doc}` which we already use, but IIRC that requires an entire file to be included.

[..]

If we wanted to include some documentation details in more than one place, then we'd have to add one file for each piece of docs (AFAICT). That doesn't make it easier to maintain.

    Yeah, that's what I feared, but I thought maaaaybe there was a way to bracket sections, give them a single name, and then \include that, pulling in a copy of all that text.

    From what I can tell, a possible route is to use @defgroup in the "Drawing Things" section, and then pull in the function/method docs by using @addtogroup <some_name> and then use @{ and @} to bracket them for capture by the "Drawing Things" section.

    Or something like that.

    Otherwise, I guess we just leave it as is, maintaining duplicate docs, as I don't think we want to dump the "drawing things" section..

[Albrecht Schlosser]

On 8/29/26 21:37 Greg Ercolano wrote:
> I guess we just leave it as is, maintaining duplicate docs, as I don't
> think we want to dump the "drawing things" section..

Not exactly "duplicate docs", but yes, somehow. I believe the "drawing
things" section should be considered as a global description, or
tutorial, whereas the documentation of the specific functions is the
"reference manual". Both should be linked together so users can jump
from one to the other. Currently we have mostly links from the "drawing
things" section to the reference section, just by mentioning the
function name which is automatically represented as a link. I imagine to
also have links from the specific functions to the "drawing things"
section wherever useful (to explain details only once). Or something
like that...