Added arc documentation

[pauljurczak]

No description provided.

[jmwright]

@pauljurczak Please merge CQ's current master branch into your fork to fix the failing CI checks.

[jmwright]

@pauljurczak Thanks for the contribution.

Straight-forward doc change, merging with only one review.

[lorenzncode]

I would recommend to revert this doc change for following reasons (at least wait for special handling in the docs for multimethod).

1. Sketch methods including arc, segment, spline make use of multimethod and now the docstrings are inconsistent.

   A docstring is defined on only the first of each of these methods currently.

   Prior to this change, the docstrings were generic.

   arc Construct an arc.

   segment Construct a segment.

   spline Construct a spline edge.

   After this change, the arc docstring is specific to the first multimethod where the segment, spline docstrings remain generic.

2. It is inconsistent to add a specific docstring for the Edge.makeThreePointArc(Vector(p1), Vector(p2), Vector(p3)) implementation but not the other two registered variants.

3. The original docstring IMO is preferred at this time because the HTML docs would require special handling if a docstring were to be added to each registered multimethod.

   Here is an example that shows the corrupt output with placeholder docstrings without special autodoc handling.

4. Let's ignore the HTML docs - would adding 3 new docstrings to the arc multimethods help the user better understand these methods? IMO, no, it would add little value. If you are reading the source directly, it should become apparent from the signature and the definition itself. The first arc method is basically a single line of code, the second two lines, and the third a few more.

Perhaps after some work to implement special autodoc handling for multimethod, docstrings could be added to each registered method. For arc it could be something like:

Construct an arc through three points

Construct an arc from current endpoint and two points

Construct an arc given center, radius, and angles

Until then, manually created documentation/examples could cover the various methods.

[pauljurczak]

I would recommend to revert this doc change for following reasons (at least wait for special handling in the docs for multimethod).

I was planning to document the other arc methods, too. I wanted to find out first if it affects the general documentation structure, which was/is unknown to me. You are making very good points that it is not consistent with its current structure.

would adding 3 new docstrings to the arc multimethods help the user better understand these methods? IMO, no, it would add little value

Whatever final shape the documentation takes, adding geometrically unambiguous descriptions to arc methods is necessary for newbies like me. Preferably reachable through HTML documentation search, not browsing through the source code.

[adam-urbanczyk]

Hm, I'm agreeing with @lorenzncode on that one.

[jmwright]

@lorenzncode Feel free to revert this for now. I won't be at a keyboard and able to do this until sometime on Monday.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.32%. Comparing base (6217431) to head (252c9dd).
Report is 355 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1049   +/-   ##
=======================================
  Coverage   96.32%   96.32%           
=======================================
  Files          40       40           
  Lines        9407     9407           
  Branches     1248     1248           
=======================================
  Hits         9061     9061           
  Misses        204      204           
  Partials      142      142           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.