Thread: Creating a regex script that functions to keep the API uniform (including the wiki)

[Kunda1]

When we document the commands, we normally document the properties that are visible in the property editor as this information is what really describes how the object works. These properties are what is saved and restored when you open a document.

So, this is another example of inconsistent behavior.

(1) The property is called "BaseFeature".
(2) In the property editor, it is displayed as "Base Feature".
(3) In the tree view, it is named "BaseFeature".
(4) However, the internal object class is called "PartDesign::FeatureBase".

This will start to veer us off topic, so I can split this off eventually...

I think there may be an interest to develop a script that outputs these inconsistencies. As you know I started the
"sWhatsThis" in the source code and the wiki thread and I've refined the regular expression to conveniently output the exact place (by line number) in the github source where to see said piece of code.

As the source code is dynamic we could also on a weekly or daily basis run the script to update if any lines shifted etc... do to revisions in the code.

[vocx]

As the source code is dynamic we could also on a weekly or daily basis run the script to update if any lines shifted etc... do to revisions in the code.

Good idea.

[Kunda1]

Good idea.

Cool. Would you help me identify the strings I would need to grep ?

[vocx]

Cool. Would you help me identify the strings I would need to grep ?

What strings?

The command name is the most important one; you already found all command names above.

The second thing that could be checked, but this is much more complicated, is identifying the properties in the code. All objects in the source have properties, which must be documented. If a property changes, the object will break of fail to work correctly. So, identifying all properties of the object is going to be difficult because the properties could be defined in different ways.

In Python, the properties are added usually inside the class of the object.

https://github.com/FreeCAD/FreeCAD/blob ... py#L15-L25

Code: Select all

class IfcRoot:
    def setProperties(self, obj):
        if not "IfcData" in obj.PropertiesList:
            obj.addProperty("App::PropertyMap","IfcData","IFC",QT_TRANSLATE_NOOP("App::Property","IFC data"))

        if not "IfcType" in obj.PropertiesList:
            obj.addProperty("App::PropertyEnumeration","IfcType","IFC",QT_TRANSLATE_NOOP("App::Property","The type of this object"))
            obj.IfcType = self.getCanonicalisedIfcTypes()

        if not "IfcProperties" in obj.PropertiesList:
            obj.addProperty("App::PropertyMap","IfcProperties","IFC",QT_TRANSLATE_NOOP("App::Property","IFC properties of this object"))

Every property is added with

Code: Select all

obj.addProperty("App::PropertyMap","IfcProperties", ..., ...)

The first argument is the type, and the second argument is the "Name" of that property, which will be displayed in the property editor.

But this property is tied to the class where it appears. So, in this case, you need to get the class "IfcRoot", and its properties "IfcData", "IfcType", "IfcProperties", etc. Just getting all properties in a file is not good enough. You need to know which properties correspond to which class.

In C++ it's a bit more complicated, because each property is instantiated as an object of the property type (a class itself).

https://github.com/FreeCAD/FreeCAD/blob ... .h#L32-L58

Code: Select all

namespace Part
{
class PartExport BodyBase : public Part::Feature, public App::OriginGroupExtension
{
    PROPERTY_HEADER_WITH_EXTENSIONS(Part::BodyBase);
public:
    BodyBase();
    App::PropertyLink       Tip;
    App::PropertyLink BaseFeature;

This tells you that the new object is a "BodyBase" object. It has two properties, "Tip" and "BaseFeature", both of type "App::PropertyLink". But there are many types of properties, so any object could potentially have any one of them. See property.

[openBrain]

(2) In the property editor, it is displayed as "Base Feature".

Just to notice that this is same for all properties. Property Editor when displaying property names adds a space before each upper case character (except first character of course). This isn't specific to BaseFeature.

[Kunda1]

Yes, orders of complexity larger.

What would be useful at first would be to identify and extract out the whole class from the source code,
then run regexs on that specific chunk.

[vocx]

Just to notice that this is same for all properties. Property Editor when displaying property names adds a space before each upper case character (except first character of course). This isn't specific to BaseFeature.

Correct. This is the reason when documenting the property, I document it how it appears in the property editor, because that's the interface that the user will see. How it is named internally is also important, of course, but that matters more to the programmer.

[vocx]

What would be useful at first would be to identify and extract out the whole class from the source code,
then run regexs on that specific chunk.

Luckily for you... this already exists! This is exactly the point of using a documentation system like Doxygen or Sphinx. These programs are parsers that are able to go through the source files and identify things like classes, class arguments, class attributes, class methods, etc. They can read all this and then produce a formatted html page highlighting the different parts in the structure.

So, more than re-inventing the wheel with Bash scripts and regular expressions, what would be ideal is for you to learn to use Doxygen for C++, and Sphinx for Python.

I haven't had time to investigate this, but I think we should try to use Sphinx with Breathe. This way, Sphinx would parse the Python sources, and Breathe would use Doxygen under the hood to parse the C++ code, in order to produce good programming documentation.