Try to better my life as a programmer, starting with more comments and documentation

src/ifcexpressparser/IfcDocumentation.py

@@ -0,0 +1,71 @@
+###############################################################################
+#                                                                             #
+# This file is part of IfcOpenShell.                                          #
+#                                                                             #
+# IfcOpenShell is free software: you can redistribute it and/or modify        #
+# it under the terms of the Lesser GNU General Public License as published by #
+# the Free Software Foundation, either version 3.0 of the License, or         #
+# (at your option) any later version.                                         #
+#                                                                             #
+# IfcOpenShell 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                #
+# Lesser GNU General Public License for more details.                         #
+#                                                                             #
+# You should have received a copy of the Lesser GNU General Public License    #
+# along with this program. If not, see <http://www.gnu.org/licenses/>.        #
+#                                                                             #
+###############################################################################
+
+###############################################################################
+#                                                                             #
+# This files uses the documentation files from buildingSMART to generate      #
+# descriptions from EXPRESS names that are suitable for comments in the C++   #
+# code. The .csv files used by this file are generated from the MS Office     #
+# Access database, which in turn has been generated from the IFC baseline     #
+# documentation by the IFCDOC utility provided by buildingSMART.              #
+#                                                                             #
+###############################################################################
+
+import re,csv
+import csv
+try: from html.entities import entitydefs
+except: from htmlentitydefs import entitydefs
+
+name_to_oid = {}
+oid_to_desc = {}
+oid_to_name = {}
+oid_to_pid = {}
+regices = list(zip([re.compile(s,re.M) for s in [r'<[\w\n=" \-/\.;_\t:%#,\?\(\)]+>',r'(\n[\t ]*){2,}',r'^[\t ]+','^']],['','\n\n','  ','/// ']))
+
+definition_files = ['DocEntity.csv', 'DocEnumeration.csv', 'DocDefined.csv', 'DocSelect.csv']
+for fn in definition_files:
+    with open(fn) as f:
+        for oid, name, desc in csv.reader(f, delimiter=';', quotechar='"'):
+            name_to_oid[name] = oid
+            oid_to_name[oid] = name
+            oid_to_desc[oid] = desc
+
+with open('DocEntityAttributes.csv') as f:
+    for pid, x, oid in csv.reader(f, delimiter=';', quotechar='"'):
+        oid_to_pid[oid] = pid
+        
+with open('DocAttribute.csv') as f:
+    for oid, name, desc in csv.reader(f, delimiter=';', quotechar='"'):
+        pid = oid_to_pid[oid]
+        pname = oid_to_name[pid]
+        name_to_oid[(pname, name)] = oid
+        oid_to_desc[oid] = desc
+        
+def description(item):
+    global name_to_oid, oid_to_desc, oid_to_name, oid_to_pid
+    oid = name_to_oid.get(item,0)
+    desc = oid_to_desc.get(oid,None)
+    if desc:
+        for a,b in entitydefs.items(): desc = desc.replace("&%s;"%a,b)
+        desc = desc.replace("\r","")
+        for r,s in regices[:-1]: desc = r.sub(s,desc)
+        desc = desc.strip()
+        r,s = regices[-1]
+        desc = r.sub(s,desc)
+    return desc

src/ifcexpressparser/IfcExpressParser.py

@@ -34,6 +34,8 @@ header = """
 ###############################################################################
 
 import os, sys
+import IfcDocumentation
+
 filename = sys.argv[1]
 
 #
@@ -160,12 +162,14 @@ class Typedef:
             self.len = len(self.type)
         elif isinstance(self.type,SelectType): selections.add(self.name)
         simple_types.add(self.name)
+        comment = IfcDocumentation.description(self.name)
+        self.comment = comment+"\n" if comment else ''
     def __str__(self):
         global generator_mode
         if generator_mode == 'HEADER' and isinstance(self.type,EnumType):
-            return ("namespace %(name)s {typedef %(type)s %(name)s;\nstd::string ToString(%(name)s v);\n%(name)s FromString(const std::string& s);}"%self.__dict__)%self.__dict__
+            return ("namespace %(name)s {\n%(comment)stypedef %(type)s %(name)s;\nstd::string ToString(%(name)s v);\n%(name)s FromString(const std::string& s);\n}"%self.__dict__)%self.__dict__
         elif generator_mode == 'HEADER':
-            return "typedef %s %s;"%(self.type,self.name)
+            return "%stypedef %s %s;"%(self.comment,self.type,self.name)
         elif generator_mode == 'SOURCE' and isinstance(self.type,EnumType):
             generator_mode = 'SOURCE_TO'
             s =  "std::string %(name)s::ToString(%(name)s v) {\n    if ( v < 0 || v >= %(len)d ) throw IfcException(\"Unable to find find keyword in schema\");\n    const char* names[] = %(type)s;\n    return names[v];\n}\n"%self.__dict__
@@ -185,7 +189,7 @@ class ArgumentList:
         s = ""
         argv = self.argstart
         for a in self.l:
-            class_name = indent = ""
+            class_name = indent = comment = optional_comment = ""
             return_type = str(a.type)
             if generator_mode == 'SOURCE':
                 class_name = "%(class_name)s::"
@@ -204,13 +208,17 @@ class ArgumentList:
                 function_body2 = " { return !entity->getArgument(%d)->isNull(); }"%argv
             else:
                 indent = "    "
-                function_body = function_body2 = ";"            
-            if a.optional: s += "\n%sbool %shas%s()%s"%(indent,class_name,a.name,function_body2)
+                function_body = function_body2 = ";"
+                comment = IfcDocumentation.description((self.class_name,a.name))
+                comment = comment+"\n" if comment else ''
+                comment = comment.replace("///","%s///"%indent)
+                optional_comment = "%s/// Whether the optional attribute %s is defined for this %s\n"%(indent,a.name,self.class_name)
+            if a.optional: s += "\n%s%sbool %shas%s()%s"%(optional_comment,indent,class_name,a.name,function_body2)
             if ( str(a.type) in enumerations ):
                 return_type = "%(type)s::%(type)s"%a.__dict__
             elif ( str(a.type) in entity_names ):
                 return_type = "%(type)s*"%a.__dict__
-            s += "\n%s%s %s%s()%s"%(indent,return_type,class_name,a.name,function_body)
+            s += "\n%s%s%s %s%s()%s"%(comment,indent,return_type,class_name,a.name,function_body)
             argv += 1
         return s
 class InverseList:
@@ -228,12 +236,15 @@ class InverseList:
 class Classdef:
     def __init__(self,l):
         self.class_name, self.parent_class, self.arguments, self.inverse = l
+        self.arguments.class_name = self.class_name
         entity_names.add(self.class_name)
         parent_relations[self.class_name] = self.parent_class
         argument_count[self.class_name] = len(self.arguments)
     def __str__(self):
         if generator_mode == 'HEADER':
-            return "class %s : public %s {\npublic:%s%s%s\n};" % (self.class_name,
+            comment = IfcDocumentation.description(self.class_name)
+            comment = comment+"\n" if comment else ''
+            return "%sclass %s : public %s {\npublic:%s%s%s\n};" % (comment,self.class_name,
                 "IfcBaseClass" if self.parent_class is None else self.parent_class,
                 self.arguments,
                 self.inverse,
@@ -247,7 +258,7 @@ class Classdef:
             )
         elif generator_mode == 'SOURCE':
             self.arguments.argstart = argument_start(self.class_name)
-            return (("\n// %(class_name)s"+str(self.arguments)+str(self.inverse)+
+            return (("\n// Function implementations for %(class_name)s"+str(self.arguments)+str(self.inverse)+
             ("\nbool %(class_name)s::is(Type::Enum v) const { return v == Type::%(class_name)s; }" if self.parent_class is None else
             "\nbool %(class_name)s::is(Type::Enum v) const { return v == Type::%(class_name)s || %(parent_class)s::is(v); }")+
             "\nType::Enum %(class_name)s::type() const { return Type::%(class_name)s; }"+