* various additional comments and comment fixes

git-svn-id: branches/wpo@11901 -

compiler/optvirt.pas

@@ -255,7 +255,8 @@ unit optvirt;
           begin
             { recursively add parent, of which we have no info about whether or not it is
               instantiated at this point -> default to false (will be overridden by "true"
-              if necessary)
+              if this class is instantioted, since then registerinstantiatedobjdef() will
+              be called for this class as well)
             }
             result:=registerinstantiatedobjectdefrecursive(def.childof,false);
             { and add ourselves to the parent }
@@ -284,7 +285,7 @@ unit optvirt;
         if (def.typ=objectdef) then
           classrefdefs.add(def)
         else
-          internalerror(2008092401);
+          internalerror(2008101401);
       end;
 
 
@@ -411,7 +412,7 @@ unit optvirt;
                   if not assigned(currnode.def.vmtentries) then
                     break;
                 end;
-              { stop when this method is does not exist in a parent }
+              { stop when this method does not exist in a parent }
               if (currnode.def.vmtentries.count<=i) then
                 break;
               
@@ -442,6 +443,7 @@ unit optvirt;
                       {$IFDEF DEBUG_DEVIRT}
                       writeln('    marking as non-static for ',currnode.def.typename);
                       {$ENDIF}
+                      { this vmt entry must also remain virtual for all parents }
                       makeallvirtual:=true;
                       currnode.def.vmcallstaticinfo^[i]:=vmcs_no;
                     end;
@@ -452,7 +454,7 @@ unit optvirt;
                   {$IFDEF DEBUG_DEVIRT}
                   writeln('    not processing parents, already non-static for ',currnode.def.typename);
                   {$ENDIF}
-                  { parents are also already set to vmcs_no, so no need to continue }
+                  { parents are already set to vmcs_no, so no need to continue }
                   currnode:=nil;
                 end;
             until not assigned(currnode) or
@@ -717,7 +719,7 @@ unit optvirt;
            a type defined in the implementation of one unit in another unit).
 
            Here, we want to record all classes constructed anywhere in the
-           program, also if those class(refdef) types are defined in the
+           program, also if those class(ref) types are defined in the
            implementation of a unit. So reset the state of all defs in
            implementation sections before starting the collection process. }
          reset_all_impl_defs;
@@ -792,7 +794,7 @@ unit optvirt;
               removed from their symtable but not from the module's deflist)
 
               procedure-local (or class-local) class definitions do not (yet)
-              exit, so it's enough to just walk the global and localsymtables
+              exit, so it's enough to just walk the global and local symtables
             }
             { globalsymtable (interface), is nil for main program itself }
             if assigned(hp.globalsymtable) then
@@ -813,6 +815,7 @@ unit optvirt;
          inheritancetree.free;
       end;
 
+
     function tprogdevirtinfo.addunitifnew(const n: shortstring): tunitdevirtinfo;
       begin
         if assigned(funits) then
@@ -828,11 +831,13 @@ unit optvirt;
           end;
       end;
 
+
     function tprogdevirtinfo.findunit(const n: shortstring): tunitdevirtinfo;
       begin
         result:=tunitdevirtinfo(funits.find(n));
       end;
 
+
     procedure tprogdevirtinfo.loadfromwpofilesection(reader: twposectionreaderintf);
       var
         unitid,
@@ -914,6 +919,7 @@ unit optvirt;
         until false;
       end;
 
+
     procedure tprogdevirtinfo.storewpofilesection(writer: twposectionwriterintf);
       var
         unitcount,
@@ -945,6 +951,7 @@ unit optvirt;
           end;
       end;
 
+
     function tprogdevirtinfo.staticnameforvirtualmethod(objdef, procdef: tdef; out staticname: string): boolean;
       var
         unitid,
@@ -956,7 +963,7 @@ unit optvirt;
         realobjdef: tobjectdef;
       begin
          { class methods are in the regular vmt, so we can handle classrefs
-           the same as plain objectdefs
+           the same way as plain objectdefs
          }
          if (objdef.typ=classrefdef) then
            realobjdef:=tobjectdef(tclassrefdef(objdef).pointeddef)
@@ -971,7 +978,7 @@ unit optvirt;
            end;
 
          { get the component names for the class/procdef combo }
-         defsdecompose(realobjdef, tprocdef(procdef),unitid,classid,vmtentry);
+         defsdecompose(realobjdef,tprocdef(procdef),unitid,classid,vmtentry);
 
          { do we have any info for this unit? }
          unitdevirtinfo:=findunit(unitid^);

compiler/wpobase.pas

@@ -69,7 +69,7 @@ type
     }
     class function getwpotype: twpotype; virtual; abstract;
 
-    { whole program optimizations for which this class generated information }
+    { whole program optimizations for which this class generates information }
     class function generatesinfoforwposwitches: twpoptimizerswitches; virtual; abstract;
 
     { whole program optimizations performed by this class }
@@ -93,7 +93,7 @@ type
     }
     procedure storewpofilesection(writer: twposectionwriterintf); virtual; abstract;
 
-    { extracts the informations pertinent to this whole program optimization
+    { extracts the information pertinent to this whole program optimization
       from the current compiler state (loaded units, ...)
     }
     procedure constructfromcompilerstate; virtual; abstract;
@@ -143,7 +143,7 @@ type
   twpofilewriter = class(tobject,twposectionwriterintf)
    private
     { array of class *instances* that wish to be written out to the
-      whole program optimization
+      whole program optimization feedback file
     }
     fsectioncontents: tfpobjectlist;
 
@@ -161,6 +161,9 @@ type
     { writes s to the wpo file }
     procedure sectionputline(const s: string);
 
+    { register a component instance that needs to be written
+      to the wpo feedback file
+    }
     procedure registerwpocomponent(component: twpocomponentbase);
   end;
 
@@ -202,8 +205,9 @@ type
 
   { method devirtualisation }
   twpodevirtualisationhandler = class(twpocomponentbase)
-    { checks whether def (a procdef for a virtual method) can be replaced with
-      a static call, and if so returns the mangled name in staticname.
+    { checks whether procdef (a procdef for a virtual method) can be replaced with
+      a static call when it's called as objdef.procdef, and if so returns the
+      mangled name in staticname.
     }
     function staticnameforvirtualmethod(objdef, procdef: tdef; out staticname: string): boolean; virtual; abstract;
   end;
@@ -227,25 +231,46 @@ type
   twpoinfomanagerbase = class
    private
     { array of classrefs of handler classes for the various kinds of whole
-      program optimization that we support
+      program optimizations that we support
     }
     fwpocomponents: tfphashlist;
 
     freader: twpofilereader;
     fwriter: twpofilewriter;
    public
-    procedure registerwpocomponentclass(wpocomponent: twpocomponentbaseclass);
-    function gethandlerforsection(const secname: string): twpocomponentbaseclass;
-
     { instances of the various optimizers/information collectors (for
       information used during this compilation)
     }
     wpoinfouse: array[twpotype] of twpocomponentbase;
 
+    { register a whole program optimization class type }
+    procedure registerwpocomponentclass(wpocomponent: twpocomponentbaseclass);
+
+    { get the program optimization class type that can parse the contents
+      of the section with name "secname" in the wpo feedback file
+    }
+    function gethandlerforsection(const secname: string): twpocomponentbaseclass;
+
+    { tell all instantiated wpo component classes to collect the information
+      from the global compiler state that they need (done at the very end of
+      the compilation process)
+    }
     procedure extractwpoinfofromprogram;
 
+    { set the name of the feedback file from which all whole-program information
+      to be used during the current compilation will be read
+    }
     procedure setwpoinputfile(const fn: tcmdstr);
+
+    { set the name of the feedback file to which all whole-program information
+      collected during the current compilation will be written
+    }
     procedure setwpooutputfile(const fn: tcmdstr);
+
+    { check whether the specified wpo options (-FW/-Fw/-OW/-Ow) are complete
+      and sensical, and parse the wpo feedback file specified with
+      setwpoinputfile
+    }
     procedure parseandcheckwpoinfo;
 
     { routines accessing the optimizer information }
@@ -253,7 +278,7 @@ type
     function can_be_devirtualized(objdef, procdef: tdef; out name: shortstring): boolean; virtual; abstract;
     { 2) optimal replacement method name in vmt }
     function optimized_name_for_vmt(objdef, procdef: tdef; out name: shortstring): boolean; virtual; abstract;
-    { 3) is a symbol in the final binary (i.e., not removed by dead code stripping/smart linking).
+    { 3) does a symbol appear in the final binary (i.e., not removed by dead code stripping/smart linking).
         WARNING: do *not* call for inline functions/procedures/methods/...
     }
     function symbol_live(const name: shortstring): boolean; virtual; abstract;