Self Documenting Tools

Any chance of getting the tools to self document? Potentially this allows using tool code to maintain https://docs.librecad.org/en/2.2.0_a/ref/tools.html in the manual.

If a reasonable template and instructions were set up then someone with a low level of expertise might be able to add the detail.

Previous discussion: https://librecad.zulipchat.com/#narrow/channel/122956-Codebase/topic/V3.20GUI/near/203240021

Well, you're right - there were several tools were added, so the end-user documentation becomes critical.

However, I'm not sure I understand what do you mean by "Self-document" - could you please expand on this?

I suspect that the only way to prepare user manual for features is .. well, just to write it. But probably I'm missing something there and you have something else in mind.

It would be best to refer to the previous discussion I linked about the implementation in LC3.

The scope would be the manual reference section tables (which don't contain any interpretation) ensuring all tools are documented. It's my understanding this is fairly basic contemporary programming. I'm thinking of https://peps.python.org/pep-0257/#what-is-a-docstring

I imagine the process would be to generate a table for each tool category (https://docs.librecad.org/en/2.2.0_a/ref/tools.html) containing Name, Icon, Command, Description. Maybe it could extend to toolbars and widgets. The documentation team could take it from there, and if the process was straightforward, might even be able to add the descriptions to the code with developer guidance.

johnfound wrote

...just proves my rule #2:
"In the software design, every list dreams to become a tree."

Yes, I've checked the discussion and well, yes, now I see your point...

Well, indeed, there are several tools for documenting the code (like Doxygen, QDoc, STANDARDESE, etc. - for C++, to name a few).

However, they are rather oriented to documenting of the "source code" - and therefore, they use such notions as "class", "header", "function" etc.  for making documentation.

Therefore, for producing the user manual - such a documentation on the source layer seems to be not (at least, directly) applicable. For example, some feature (or action) may involve lot's of files, functions, classes etc. and documenting them is too low-level and not informative for the end user.  

Therefore, I'm afraid the only way to go there - is just to create manual documentation for features.  

At least, right now I have no idea how to use the code documentation approach/tool to achieve some useful output...

With my merge request I usually add description for the added functionality (located here: https://github.com/LibreCAD/LibreCAD/tree/master/ChangeLogs), yet still it's quite brief to be useful for the end user.

https://forum.librecad.org/Explode-not-anymore-as-a-command-tp5727004p5727005.html

sand1024 wrote

you can always check the list of supported commands just by pressing TAB in command line input (in Cmd widget)

That would be a good start for a script to automate the reference section of the manual by updating https://raw.githubusercontent.com/LibreCAD/docs/refs/heads/2.2.0/ref/tools.rst

Yes, it's definitely possible! If tools are set up to include self-documenting code (like comments or metadata), it can automatically generate parts of the manual. With a clear template and simple steps, even beginners could help keep the docs up-to-date.

From the Manual:

"Tool" "Icon" "Command" "Shortcut" "Description"
"Line (2 Points)" "—" "l li line" "L" "Draw a straight line between two points"
"Rectangle" "—" "rec rect rectangle" "R" "Draw rectangle by corners"
"Circle (Center Point)" "—" "ci circle" "C" "Create circle center + radius"
"Circle (2 Points)" "—" "c2 c2p" "—" "Circle through two points"
"Circle (3 Points)" "—" "c3 c3p" "—" "Circle through three points"
"Line Parallel" "—" "pa o offset parallel" "P" "Draw parallel line"
"Line Parallel Through Point" "—" "pp ptp" "—" "Parallel through point"
"Line Vertical" "—" "ver vertical" "V" "Vertical line"
"Line Horizontal" "—" "hor horizontal" "H" "Horizontal line"
"Line Orthogonal" "—" "ortho perp" "O" "Perpendicular line"
"Line Relative Angle" "—" "relang" "—" "Relative angle line"
"Line Bisector" "—" "bi bisect" "—" "Angle bisector"
"Line Tangent (Point Circle)" "—" "tanpc tangentpc" "—" "Tangent from point to circle"
"Line Tangent (Circle Circle)" "—" "tan2c" "—" "Tangent between two circles"
"Arc (3 Points)" "—" "a ar arc" "A" "Arc via three points"
"Arc Tangential" "—" "t3 arctan" "—" "Arc tangent"
"Circle Tangent 3" "—" "ct3 tan3" "—" "Circle tangent to 3 entities"
"Ellipse (Axis)" "—" "ea ellipsec2p" "—" "Ellipse by center and axis"
"Ellipse Foci Point" "—" "ef ellipse3p" "—" "Ellipse with foci points"
"Ellipse 4 Points" "—" "e4 ellipse4p" "—" "Ellipse through 4 points"
"Ellipse Inscribed" "—" "ei ie" "—" "Inscribed ellipse"
"Polyline" "—" "pl polyline" "P" "Sketch connected lines"
"Freehand Line" "—" "fhl free" "—" "Draw freehand line"
"Spline" "—" "spl spline" "—" "Draw spline curve"
"Spline through Points" "—" "stp spline2" "—" "Spline through points"
"Hatch" "—" "ha hatch" "H" "Hatch fill"
"Text (Single Line)" "—" "txt text" "T" "Insert text"
"Text (MText)" "—" "mtxt mtext" "M" "Multi-line text"
"Point" "—" "po point" "—" "Insert point"
"Aligned Dimension" "—" "da" "—" "Aligned dimension"
"Linear Dimension" "—" "dr" "—" "Linear dimension"
"Horizontal Dimension" "—" "dh" "—" "Horizontal dimension"
"Vertical Dimension" "—" "dv" "—" "Vertical dimension"
"Radial Dimension" "—" "dimradial" "—" "Radial dimension"
"Diametric Dimension" "—" "dimdiameter" "—" "Diametric dimension"
"Angular Dimension" "—" "dimangular" "—" "Angular dimension"
"Leader" "—" "ld" "—" "Leader line"
"Move / Copy" "—" "mv" "Ctrl+M" "Move or copy"
"Rotate" "—" "ro" "Ctrl+R" "Rotate"
"Scale" "—" "sz" "Ctrl+S" "Scale"
"Mirror" "—" "mi" "Ctrl+Shift+M" "Mirror entities"
"Offset" "—" "mo pa offset parallel" "—" "Offset"
"Trim" "—" "tm trim" "—" "Trim entities"
"Stretch" "—" "ss" "—" "Stretch"
"Lengthen" "—" "le" "—" "Lengthen entity"
"Bevel" "—" "ch bevel" "—" "Bevel/chamfer"
"Fillet" "—" "fi fillet" "—" "Fillet/round corner"
"Divide" "—" "di div cut" "—" "Divide/cut"
"Properties" "—" "mp prop" "—" "Modify properties"
"Zoom In/Out" "—" "za zr" "Ctrl+Mouse" "Zoom view"
"Pan" "—" "zp" "Mouse drag" "Pan view"
"Undo" "—" "un u" "Ctrl+Z" "Undo"
"Redo" "—" "rd r" "Ctrl+Y" "Redo"
"Select All" "—" "sa" "Ctrl+A" "Select all entities"
"Deselect All" "—" "sx" "Ctrl+K" "Deselect all"

From the consolidated list in lc_commandItems.h, examining any commands or abbreviations not reflected in the simplified table of common tools, shortcuts, and descriptions reveals the following notable commands absent or not clearly listed in the manual:

Snake line forms: "sline" (sli, sl), "slinex" (slix, slx), "sliney" (sliy, sly) — specialized line types not documented in the main table.
Multiple rectangle variants: "rect1" (re1), "rect2" (re2), "rect3" (re3) — one, two, or three point rectangle drawing commands.
Line join: "linejoin" (lj) — for joining lines.
Break or divide entity: "breakdivide" (bd).
Line gap: "gapline" (gl) — create a gap in a line.
More polygon drawing variants: "polygoncencor" (pp, polycp, pcp), "polygoncentan" (pv, polyct), "polygonvv" (pvv), "polygon2v" (p2, poly2).
Circle tangent to 2 circles and 1 point: "circletan2cp" (tr).
Circle tangent to two points: "circletan2p" (td).
Circle tangent to two circles with radius: "circletan2cr" (tc).
Various arc commands like "arc2pr" (a2r), "arc2pl" (a2l), "arc2ph" (a2h), "arc2pa" (a2a).
Polyline edit commands: "plineadd" (pi), "plineapp" (pn), "plinedel" (pd), "plinedeltwn" (pr), "plinetrm" (pt), "plinepar" (pe), "plinejoin" (pj).
Select commands beyond select/deselect all: "invertselect" (is).
Snap commands: exclusive snap (snapexcl, sx, ex) commented out, and multiple snapping modes such as "snapmiddlemanual" (smm).
Set relative zero: "setrelativezero" (rz).
Restrict commands for snapping: "restrictnothing" (rn), "restrictorthogonal" (rr), "restricthorizontal" (rh), "restrictvertical" (rv).

These commands mostly represent specialized drawing formats, entity editing, advanced snapping, polygon and polyline manipulations, and selection enhancements that the simplified table does not fully catalog but are part of LibreCAD's full command set.

It would be a fairly simple thing for our developers to maintain the table of commands.

flywire wrote

"Tool" "Icon" "Command" "Shortcut" "Description"
"Line (2 Points)" "—" "l li line" "L" "Draw a straight line between two points"

Icons seem to be defined in three places: actionfactory, toolbar and menu.

Would \librecad\src\ui\main\init\lc_actionfactory.cpp be the definitive source?

         {"DrawLine",                 RS2::ActionDrawLine,                tr("&2 Points"),              ":/icons/line_2p.lci"},

In general terms how is ":/icons/line_2p.lci" converted to ":/icons/line_2p.svg"?
Would it be reasonable to just substitute the extension for documentation purposes?

This code looks like a good candidate for replacing with a json file.

>Icons seem to be defined in three places: actionfactory, toolbar and menu.

Well, mostly - yes, but some of them might be also a part of widgets UI.

But - all itcons are listed in resource files. These files has .qrc extension, and /res/icons/icons.qrc contains SVG icons used in UI.

>Would \librecad\src\ui\main\init\lc_actionfactory.cpp be the definitive source?

Yes, most of actions are defined there.

>In general terms how is ":/icons/line_2p.lci" converted to ":/icons/line_2p.svg"?

.lci is just an alias for .svg. If the code somwhere in LibreCAD requests the image resource with .lci extension, the custom icon engine is invoked and performs the process of color subsitutions within that svg (built-in colors are replaced by the user defined colors, specified in Widget Options).  

This alows to change colors for icons as well as load icons from the external source (disk location).

More information about icons styling and colors substition process might be found there:

https://github.com/LibreCAD/LibreCAD/pull/2078

> This code looks like a good candidate for replacing with a json file.

Well, theoretically yes, but what for? That mapping is quite sensitive, plus includes information about translation (performed on runtine) as well as internal code of the action.  

If necessary, it is possible just to override built-in icon by the external one (of course, the name should be the same).

Thank you for your comments. It’s a good start, but I’d need more detail to be able to the documentation. At present, too many definitions are scattered throughout different C++ files making exploration and modification cumbersome.

sand1024 wrote

> This code looks like a good candidate for replacing with a json file.

Well, theoretically yes, but what for?

Using JSON as a declarative configuration layer would extend LibreCAD’s data‑driven architecture, an approach already adopted in LibreCAD 3 where structure and presentation are deliberately separated from executable logic. LibreCAD 2 likewise separates the core engine from the data, but much of that data is still wrapped inside C++ source files.

Benefits of a JSON-Based Configuration

1. Maintainability and Extendibility

* Simplifies adding or modifying UI elements without touching C++ code.
A toolbar layout or command button change becomes a JSON edit, not a recompile.

* Reduces merge conflicts, since UI structure changes occur outside the C++ logic layer.

2. Localization and Theming Flexibility

* JSON can include translation keys, icon aliases, and theme references, avoiding scattered tr() calls.
* Enables customization beyond development cycles—users or distributions could adjust icon sets, naming schemes, or menu layouts.

3. Simplified Icon Management

* Reduces friction between .qrc, .svg, and .lci mappings.
For instance:

json
{
  "command": "line_2p",
  "label": "Line, two points",
  "icon": ":/icons/line_2p.svg",
  "shortcut": "L,1"
}

* The existing color substitution system could load icons dynamically, removing the need to rebuild resources.

4. Consistent Command Definitions Across Menus, Toolbars, and Widgets

Shared JSON metadata can generate multiple UI components:

* Menus (File, Edit, Draw)
* Toolbars (icon placement, order, grouping)
* Command palette or search features

* This ensures consistency and avoids duplication across actionfactory, menu, and toolbar code.

5. Easier Testing and Theming

* Developers could load alternative configurations (e.g., minimal vs full UI) simply by switching JSON files.
* Automated tests could validate JSON integrity without launching the full application.

6. Plugin and External Integration

* Plugins could register commands declaratively via JSON instead of compiled C++.
* A plugin’s own plugin_actions.json could extend existing menus or add new tool groups cleanly.

well, yes, declarative configuration is a good thing indeed. I'll think whether more declarative style may be added.

However, I really doubt that it might be fully achived in this particualr case.  

Actions UI (theoretically) may be described via JSON. Something like a combination of UI attributes.
["action_name", "icon", "text", "tooltip"]. Yet later, there still will be a code that will tie internal actions with their UI.  

Plus, that will complicate localization - that relies on tr() calls (for Linguist or so).

The major point agains building menus and toolbars from the metadata - it's conditional logic, where the structure of the menu, for example, depends on some various conditions (like entity-aware context menu that i've added in my last PR, or main menu).

The simplest cases with just a list of actions - well, they are already covered by Toolbar Creator or Menu Creator tools.  

flywire wrote

* The existing color substitution system could load icons dynamically, removing the need to rebuild resources.

It does already - at least for external files.

flywire wrote

* Developers could load alternative configurations (e.g., minimal vs full UI) simply by switching JSON files

I think Workspaces are more suitable for this task - https://github.com/LibreCAD/LibreCAD/pull/2078 

Demo for Workspaces is there https://youtu.be/FwvXs1eDYBA
 
Plugin API... well, it's limited indded and should be reviewed and reworked.