From ed8eab273d2792d95bca85c5e8ddc7dd8d19b866 Mon Sep 17 00:00:00 2001
From: DeepSOIC <vv.titov@gmail.com>
Date: Thu, 19 Nov 2015 02:53:48 +0300
Subject: [PATCH] API: Update docu strings of methods of BSplineCurve

Mainly exposing argument types and meanings, but also updating a few
descriptions by copy-paste-editing documentation of corresponding
OpenCASCADE.
---
 src/Mod/Part/App/BSplineCurvePy.xml | 73 +++++++++++++++++++++++++----
 1 file changed, 64 insertions(+), 9 deletions(-)

diff --git a/src/Mod/Part/App/BSplineCurvePy.xml b/src/Mod/Part/App/BSplineCurvePy.xml
index 2e5cb2ff5..c7b7ab507 100644
--- a/src/Mod/Part/App/BSplineCurvePy.xml
+++ b/src/Mod/Part/App/BSplineCurvePy.xml
@@ -109,27 +109,60 @@ done if Degree is less than or equal to the current degree.</UserDocu>
 		</Methode>
 		<Methode Name="increaseMultiplicity">
 			<Documentation>
-				<UserDocu>Increases the multiplicity</UserDocu>
+				<UserDocu>
+				increaseMultiplicity(int index, int mult)
+				increaseMultiplicity(int start, int end, int mult)
+				Increases multiplicity of knots up to mult.
+
+				index: the index of a knot to modify (1-based)
+				start, end: index range of knots to modify.
+				If mult is lower or equal to the current multiplicity nothing is done. If mult is higher than the degree the degree is used.
+				</UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="incrementMultiplicity">
 			<Documentation>
-				<UserDocu>Increases the multiplicity</UserDocu>
+				<UserDocu>
+				incrementMultiplicity(int start, int end, int mult)
+				Raises multiplicity of knots by mult.
+
+				start, end: index range of knots to modify.
+				</UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="insertKnot">
 			<Documentation>
-				<UserDocu>Inserts knot.</UserDocu>
+				<UserDocu>
+				insertKnot(u, mult = 1, tol = 0.0)
+				Inserts a knot value in the sequence of knots. If u is an existing knot the 
+				multiplicity is increased by mult. </UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="insertKnots">
 			<Documentation>
-				<UserDocu>Inserts knots.</UserDocu>
+				<UserDocu>
+				insertKnots(list_of_floats, list_of_ints, tol = 0.0, bool_add = True)
+				Inserts a set of knots values in the sequence of knots.
+
+				For each u = list_of_floats[i], mult = list_of_ints[i]
+
+				If u is an existing knot the multiplicity is increased by mult if bool_add is 
+				True, otherwise increased to mult.
+
+				If u is not on the parameter range nothing is done.
+
+				If the multiplicity is negative or null nothing is done. The new multiplicity 
+				is limited to the degree.
+
+				The tolerance criterion for knots equality is the max of Epsilon(U) and ParametricTolerance.
+				</UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="removeKnot">
 			<Documentation>
 				<UserDocu>
+					removeKnot(Index, M, tol)
+
 					Reduces the multiplicity of the knot of index Index to M.
 					If M is equal to 0, the knot is removed.
 					With a modification of this type, the array of poles is also modified.
@@ -147,7 +180,9 @@ done if Degree is less than or equal to the current degree.</UserDocu>
 		</Methode>
 		<Methode Name="segment">
 			<Documentation>
-				<UserDocu>Modifies this B-Spline curve by segmenting it.</UserDocu>
+				<UserDocu>
+					segment(u1,u2)
+					Modifies this B-Spline curve by segmenting it.</UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="setKnot">
@@ -217,11 +252,14 @@ ensures that:
 		</Methode>
 		<Methode Name="movePoint">
 			<Documentation>
-				<UserDocu>Moves the point of parameter U of this B-Spline curve to P.
+				<UserDocu>
+				movePoint(U, P, Index1, Index2)
+				Moves the point of parameter U of this B-Spline curve to P.
 Index1 and Index2 are the indexes in the table of poles of this B-Spline curve
 of the first and last poles designated to be moved.
-FirstModifiedPole and LastModifiedPole are the indexes of the first and last
-poles which are effectively modified.</UserDocu>
+
+Returns: (FirstModifiedPole, LastModifiedPole). They are the indexes of the 
+first and last poles which are effectively modified.</UserDocu>
 			</Documentation>
 		</Methode>
 		<Methode Name="setNotPeriodic">
@@ -258,6 +296,8 @@ from the knots table of this B-Spline curve.</UserDocu>
 		<Methode Name="approximate">
 			<Documentation>
 				<UserDocu>
+					approximate(list_of_points):
+
 					Replaces this B-Spline curve by approximating a set of points.
 				</UserDocu>
 			</Documentation>
@@ -265,7 +305,16 @@ from the knots table of this B-Spline curve.</UserDocu>
 		<Methode Name="interpolate">
 			<Documentation>
 				<UserDocu>
+					interpolate(list_of_points, bool periodic = False, float tolerance = 1e-6, 
+					tangent1 = None, tangent2 = None)
+
 					Replaces this B-Spline curve by interpolating a set of points.
+
+					Continuity of the spline defaults to C2. However, if periodic, or tangents 
+					are supplied, the continuity will drop to C1.
+
+					tangent1, tangent2 specify tangent vectors for starting and ending points 
+					of the BSpline. Either none, or both must be specified.
 				</UserDocu>
 			</Documentation>
 		</Methode>
@@ -330,7 +379,13 @@ from the knots table of this B-Spline curve.</UserDocu>
 		<Methode Name="makeC1Continuous">
 			<Documentation>
 				<UserDocu>
-					Tries to make the spline C1-continuous where possible.
+					makeC1Continuous(tol = 1e-6, ang_tol = 1e-7)
+					Reduces as far as possible the multiplicities of the knots of this BSpline 
+					(keeping the geometry). It returns a new BSpline, which could still be C0. 
+					tol is a geometrical tolerance. 
+					The tol_ang is angular tolerance, in radians. It sets tolerable angle mismatch 
+					of the tangents on the left and on the right to decide if the curve is G1 or 
+					not at a given point.
 				</UserDocu>
 			</Documentation>
 		</Methode>