From f97906c4e3d369071aef5874fcc498fc9c8564ad Mon Sep 17 00:00:00 2001
From: Pieter Hijma <pieterhijma@users.noreply.github.com>
Date: Tue, 14 Nov 2023 18:07:43 +0100
Subject: [PATCH] Add documentation for HLRBRep.PolyAlgo

---
 .../Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml   | 98 +++++++++++++++----
 1 file changed, 79 insertions(+), 19 deletions(-)

diff --git a/src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml b/src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml
index b2f219652c..828b24cebf 100644
--- a/src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml
+++ b/src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml
@@ -14,103 +14,163 @@
       Delete="false">
     <Documentation>
           <Author Licence="LGPL" Name="Werner Mayer" EMail="wmayer[at]users.sourceforge.net" />
-          <UserDocu>Describes functions to use HLR algorithm.</UserDocu>
+          <UserDocu>A framework to compute the shape as seen in a projection
+plane. This is done by calculating the visible and the hidden parts of the
+shape. HLRBRep_PolyAlgo works with three types of entity:
+
+- shapes to be visualized (these shapes must have already been triangulated.)
+- edges in these shapes (these edges are defined as polygonal lines on the
+  triangulation of the shape, and are the basic entities which will be visualized
+  or hidden), and
+- triangles in these shapes which hide the edges.
+
+HLRBRep_PolyAlgo is based on the principle of comparing each edge of the shape
+to be visualized with each of the triangles produced by the triangulation of
+the shape, and calculating the visible and the hidden parts of each edge. For a
+given projection, HLRBRep_PolyAlgo calculates a set of lines characteristic of
+the object being represented. It is also used in conjunction with the
+HLRBRep_PolyHLRToShape extraction utilities, which reconstruct a new,
+simplified shape from a selection of calculation results. This new shape is
+made up of edges, which represent the shape visualized in the
+projection. HLRBRep_PolyAlgo works with a polyhedral simplification of the
+shape whereas HLRBRep_Algo takes the shape itself into account. When you use
+HLRBRep_Algo, you obtain an exact result, whereas, when you use
+HLRBRep_PolyAlgo, you reduce computation time but obtain polygonal segments. An
+HLRBRep_PolyAlgo object provides a framework for:
+
+- defining the point of view
+- identifying the shape or shapes to be visualized
+- calculating the outlines
+- calculating the visible and hidden lines of the shape. Warning
+- Superimposed lines are not eliminated by this algorithm.
+- There must be no unfinished objects inside the shape you wish to visualize.
+- Points are not treated.
+- Note that this is not the sort of algorithm used in generating shading, which
+  calculates the visible and hidden parts of each face in a shape to be
+  visualized by comparing each face in the shape with every other face in the
+  same shape.
+
+	  </UserDocu>
     </Documentation>
     <Methode Name="load">
         <Documentation>
-            <UserDocu>
+            <UserDocu>load(S)
+
+Loads the shape S into this framework. Warning S must have already been triangulated.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="remove">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>remove(i)
+
+Remove the shape of index i from this framework.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nbShapes">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>nbShapes()
+
+Returns the number of shapes in the collection.  It does not modify the
+object's state and is used to retrieve the count of shapes.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="shape">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>shape(i) -> TopoShape
+
+Return the shape of index i.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="index">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>index(S) ->  int
+
+Return the index of the Shape S.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="setProjector" Keyword="true">
         <Documentation>
-            <UserDocu>
+            <UserDocu>setProjector(Origin=(0, 0, 0), ZDir=(0,0,0), XDir=(0,0,0), focus=NaN)
+
+Set the projector.  With focus left to NaN, an axonometric projector is
+created.  Otherwise, a perspective projector is created with focus focus.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="update">
         <Documentation>
-            <UserDocu>
-            </UserDocu>
+            <UserDocu>update()
+
+Launches calculation of outlines of the shape visualized by this
+framework. Used after setting the point of view and defining the shape or
+shapes to be visualized.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="initHide">
         <Documentation>
-            <UserDocu>
+            <UserDocu>initHide()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="moreHide">
         <Documentation>
-            <UserDocu>
+            <UserDocu>moreHide()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nextHide">
         <Documentation>
-            <UserDocu>
+            <UserDocu>nextHide()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="initShow">
         <Documentation>
-            <UserDocu>
+            <UserDocu>initShow()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="moreShow">
         <Documentation>
-            <UserDocu>
+            <UserDocu>moreShow()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nextShow">
         <Documentation>
-            <UserDocu>
+            <UserDocu>nextShow()<!-- no further documentation available -->
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLinedShape">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLinedShape(S) -> TopoShape
+
+Make a shape with the internal outlines in each face of shape S.
             </UserDocu>
         </Documentation>
     </Methode>
     <Attribute Name="Angle">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu><!-- no documentation available --></UserDocu>
         </Documentation>
         <Parameter Name="Angle" Type="Float"/>
     </Attribute>
     <Attribute Name="TolAngular">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu><!-- no documentation available --></UserDocu>
         </Documentation>
         <Parameter Name="TolAngular" Type="Float"/>
     </Attribute>
     <Attribute Name="TolCoef">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu><!-- no documentation available --></UserDocu>
         </Documentation>
         <Parameter Name="TolCoef" Type="Float"/>
     </Attribute>