Draft: update description of draftviewproviders package

src/Mod/Draft/draftviewproviders/README.md

@@ -1,25 +1,50 @@
-2020 February
-
-These files define the view provider classes of the "scripted objects"
-defined by the workbench. These scripted objects are originally
-defined in the big `Draft.py` file.
-
-Each scripted object has a creation command like `make_arc`, 
-a proxy class like `Arc`, and a view provider like `ViewProviderArc`.
-The view providers define the code that indicates how they are displayed
-in the tree view and in the 3D view, and visual properties
-such as line thickness, line color, face color, and transparency.
-These properties are only available when the graphical interface exists,
-otherwise they are ignored.
-
-Each scripted object in `draftobjects/` should import its corresponding
-view provider from this directory as long the graphical interface
+2020 May
+
+These files define the viewprovider classes for "scripted objects"
+defined within the workbench. The corresponding proxy object classes
+should be defined in the modules in `draftobjects/`.
+
+Each scripted object has a creation function like `make_rectangle`,
+a proxy class like `Rectangle`, and a viewprovider class
+like `ViewProviderRectangle`.
+The view providers define how they are displayed in the tree view
+and in the 3D view, that is, visual properties such as line thickness,
+line color, face color, and transparency.
+These properties are only available when the graphical interface is loaded;
+in a console only session, these properties cannot be read nor set.
+These properties aren't very "real" because they don't affect the actual
+geometrical shape of the object.
+Each make function in `draftmake/` should import its corresponding
+viewprovider from this package in order to set the visual properties
+of the new scripted object, as long the graphical interface
 is available.
 
-These modules should be split from the big `Draft.py` module.
+These classes were previously defined in the `Draft.py` module,
+which was very large. Now `Draft.py` is an auxiliary module
+which just loads the individual classes in order to provide backwards
+compatibility for older files.
+Other workbenches can import these classes for their own use,
+including creating derived classes.
+```py
+import Draft
+
+new_obj = App.ActiveDocument.addObject("Part::Part2DObjectPython", "New")
+
+if App.GuiUp:
+    Draft.ViewProviderRectangle(new_obj.ViewObject)
+
+
+# Subclass
+class NewViewProvider(Draft.ViewProviderRectangle):
+   ...
+```
 
-At the moment the files in this directory aren't really used,
-but are used as placeholders for when the migration of classes happens.
+As the scripted objects are rebuilt every time a document is loaded,
+this means that, in general, these modules cannot be renamed
+without risking breaking previously saved files. They can be renamed
+only if the old class can be migrated to point to a new class,
+for example, by creating a reference to the new class named the same
+as the older class.
 
 For more information see the thread:
 [[Discussion] Splitting Draft tools into their own modules](https://forum.freecadweb.org/viewtopic.php?f=23&t=38593&start=10#p341298)

src/Mod/Draft/draftviewproviders/__init__.py

@@ -1,7 +1,56 @@
-"""Classes that define the viewproviders of custom scripted objects.
+# ***************************************************************************
+# *   (c) 2020 Carlo Pavan <carlopav@gmail.com>                             *
+# *   (c) 2020 Eliud Cabrera Castillo <e.cabrera-castillo@tum.de>           *
+# *                                                                         *
+# *   This file is part of the FreeCAD CAx development system.              *
+# *                                                                         *
+# *   This program is free software; you can redistribute it and/or modify  *
+# *   it under the terms of the GNU Lesser General Public License (LGPL)    *
+# *   as published by the Free Software Foundation; either version 2 of     *
+# *   the License, or (at your option) any later version.                   *
+# *   for detail see the LICENCE text file.                                 *
+# *                                                                         *
+# *   FreeCAD is distributed in the hope that it will be useful,            *
+# *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
+# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
+# *   GNU Library General Public License for more details.                  *
+# *                                                                         *
+# *   You should have received a copy of the GNU Library General Public     *
+# *   License along with FreeCAD; if not, write to the Free Software        *
+# *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+# *   USA                                                                   *
+# *                                                                         *
+# ***************************************************************************
+"""Modules that contain classes that define viewproviders for scripted objects.
 
 These classes define viewproviders for the custom objects
-defined in `draftobjects`.
-The viewproviders can be used only when the graphical interface
-is available; in console mode the viewproviders are not available.
+defined in the `draftobjects` package.
+They extend the basic viewprovider that is installed by default
+with the creation of a base object defined in C++.
+
+These classes are not normally used by themselves, but are used at creation
+time by the make functions defined in the `draftmake` package.
+These viewproviders are installed only when the graphical interface
+is available; in console-only mode the viewproviders are not available
+so the make functions ignore them.
+
+Similar to the object classes, once a viewprovider class is assigned
+to an object, and it is saved in a document, the object's viewprovider
+will be rebuilt with the same class every time the document
+is opened. In order to do this, the viewprovider module must exist
+with the same name as when the object was saved.
+
+For example, when creating a `Rectangle`, the object uses
+the `draftviewproviders.view_rectangle.ViewProviderRectangle` class.
+This class must exist when the document is opened again.
+
+This means that, in general, these modules cannot be renamed or moved
+without risking breaking previously saved files. They can be renamed
+only if the old class can be migrated to point to a new class,
+for example, by creating a reference to the new class named the same
+as the older class.
+
+::
+
+    old_module.ViewProviderRectangle = new_module.ViewProviderRectangle
 """