rename ICEMultiDocObserver -> ICEDocumentObserver

+ improve interfaces documentation

src/ce_dcd.pas

@@ -21,9 +21,9 @@ type
    *
    * Projects folders are automatically imported: ICEProjectObserver.
    * Completion, hints and declaration finder automatically work on the current
-   *   document: ICEMultiDocObserver.
+   *   document: ICEDocumentObserver.
    *)
-  TCEDcdWrapper = class(TWritableLfmTextComponent, ICEProjectObserver, ICEMultiDocObserver)
+  TCEDcdWrapper = class(TWritableLfmTextComponent, ICEProjectObserver, ICEDocumentObserver)
   private
     fTempLines: TStringList;
     fInputSource: string;
@@ -222,7 +222,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEDcdWrapper.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_dfmt.pas

@@ -63,7 +63,7 @@ type
 
   { TCEDfmtWidget }
 
-  TCEDfmtWidget = class(TCEWidget, ICEMultiDocObserver)
+  TCEDfmtWidget = class(TCEWidget, ICEDocumentObserver)
     btnApply: TSpeedButton;
     btnCancel: TSpeedButton;
     pnlFooter: TPanel;
@@ -216,7 +216,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEDfmtWidget.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_editor.pas

@@ -51,7 +51,7 @@ type
 
   { TCEEditorWidget }
 
-  TCEEditorWidget = class(TCEWidget, ICEMultiDocObserver, ICEMultiDocHandler, ICEProjectObserver)
+  TCEEditorWidget = class(TCEWidget, ICEDocumentObserver, ICEMultiDocHandler, ICEProjectObserver)
     MenuItem1: TMenuItem;
     MenuItem10: TMenuItem;
     MenuItem11: TMenuItem;
@@ -350,7 +350,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEEditorWidget.docNew(aDoc: TCESynMemo);
 var
   pge: TCEPage;

src/ce_editoroptions.pas

@@ -123,7 +123,7 @@ type
    * Manages and exposes all the editor and highligther options to an TCEOptionsEditor.
    * It's also responsible to give the current options to a new editor.
    *)
-  TCEEditorOptions = class(TCEEditorOptionsBase, ICEEditableOptions, ICEMultiDocObserver, ICEEDitableShortcut)
+  TCEEditorOptions = class(TCEEditorOptionsBase, ICEEditableOptions, ICEDocumentObserver, ICEEDitableShortcut)
   private
     fBackup: TCEEditorOptionsBase;
     fShortcutCount: Integer;
@@ -476,7 +476,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEEditorOptions.docNew(aDoc: TCESynMemo);
 begin
   //apply...des not modify font size to preserve current zoom

src/ce_gdb.pas

@@ -168,7 +168,7 @@ type
 
 
   { TCEGdbWidget }
-  TCEGdbWidget = class(TCEWidget, ICEProjectObserver, ICEMultiDocObserver)
+  TCEGdbWidget = class(TCEWidget, ICEProjectObserver, ICEDocumentObserver)
     btnReg: TBitBtn;
     btnStack: TBitBtn;
     btnSendCom: TBitBtn;
@@ -335,7 +335,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEGdbWidget.docNew(aDoc: TCESynMemo);
 begin
   if aDoc.isDSource then

src/ce_interfaces.pas

@@ -113,8 +113,8 @@ type
   (**
    * An implementer is informed about the current file(s).
    *)
-  ICEMultiDocObserver = interface(ISubjectType)
+  ICEDocumentObserver = interface(ISubjectType)
-  ['ICEMultiDocObserver']
+  ['ICEDocumentObserver']
     // aDoc has been created (empty, runnable, project source, ...).
     procedure docNew(aDoc: TCESynMemo);
     // aDoc is the document being edited.
@@ -125,37 +125,37 @@ type
     procedure docClosing(aDoc: TCESynMemo);
   end;
   (**
-   * An implementer informs some ICEMultiDocObserver about the current file(s)
+   * An implementer informs the ICEMultiDocObserver about the current file(s)
    *)
-  TCEMultiDocSubject = specialize TCECustomSubject<ICEMultiDocObserver>;
+  TCEMultiDocSubject = specialize TCECustomSubject<ICEDocumentObserver>;
 
 
 
   (**
    * An implementer is informed about the current project(s).
-   * Usually observer should keep track of two ICECOmmonProject:
+   * Usually observer should keep track of two ICECommonProject:
-   * - the free project: the project that's not in a group and that has to
+   * - the "free standing project" (FSP): the project that's not in a group and
-   *  be freed manualy in order to be replaced.
+   * that has to be freed manualy in order to be replaced.
-   * - the current project which can be either the free project or one of the
+   * - the current project, the one that's active) which can be either the FSP
-   *  project in the group
+   * or one of the project in the group.
    *)
   ICEProjectObserver = interface(ISubjectType)
   ['ICEProjectObserver']
-    // aProject has been created/opened
+    // a project has been created/opened
     procedure projNew(aProject: ICECommonProject);
-    // aProject has been modified: switches, source name, ...
+    // a project has been modified: switches, source name, ...
     procedure projChanged(aProject: ICECommonProject);
-    // aProject is about to be closed.
+    // a project is about to be closed.
     procedure projClosing(aProject: ICECommonProject);
-    // not called yet: aProject is always the same
+    // a project is focused, it can be inGroup or not
     procedure projFocused(aProject: ICECommonProject);
-    // aProject is about to be compiled
+    // aProject is about to be compiled, time to lock related actions.
     procedure projCompiling(aProject: ICECommonProject);
-    // aProject compilation is finsihed
+    // aProject compilation is finsihed, related actions can be unlocked.
     procedure projCompiled(aProject: ICECommonProject; success: boolean);
   end;
   (**
-   * An implementer informs some ICEProjectObserver about the current project(s)
+   * An implementer informs the ICEProjectObserver about the current project(s)
    *)
   TCEProjectSubject = specialize TCECustomSubject<ICEProjectObserver>;
 
@@ -201,7 +201,7 @@ type
 
 
   (**
-   * An implementer can expose some customizable shortcuts to be edited in a dedicated widget.
+   * An implementer can expose customizable shortcuts to be edited in a dedicated widget.
    *)
   ICEEditableShortCut = interface(ISubjectType)
   ['ICEEditableShortCut']
@@ -221,13 +221,21 @@ type
 
 
 
-  // the option editor uses this value as a hint to cast and display an option container.
+  // the option editor uses this value as a hint to display an option container.
-  TOptionEditorKind = (oekGeneric, oekForm, oekControl);
+  TOptionEditorKind = (
+    oekGeneric, // the editor will display the publications of the TPersistent passed in optionedWantContainer
+    oekForm,    // the editor will cast the result of optionedWantContainer as a TForm and host this form
+    oekControl  // the editor will cast the result of optionedWantContainer as a TControl and host this control
+  );
   // event generated by the option editor and passed to an ICEEditableOptions.
-  // the oeeChange event only happends if the container is oekGeneric.
+  TOptionEditorEvent = (
-  TOptionEditorEvent = (oeeCancel, oeeAccept, oeeChange, oeeSelectCat);
+    oeeCancel,    // the "cancel" button of the option editor is pressed
+    oeeAccept,    // the "accept" button of the option editor is pressed
+    oeeChange,    // the properties of the container has changed, only happens if the container is oekGeneric.
+    oeeSelectCat  // the container is will be displayed.
+  );
   (**
-   * An implementer can expose some options to be edited in a dedicated widget.
+   * An implementer can expose options to be edited in a dedicated widget.
    *)
   ICEEditableOptions = interface(ISubjectType)
   ['ICEEditableOptions']
@@ -258,8 +266,8 @@ type
     amcProj,        // used as filter
     amcApp,         // used as filter
     amcMisc,        // used as filter
-    amcAutoEdit,    // same as amcEdit but the message data is set automatically from the widget side
+    amcAutoEdit,    // same as amcEdit but the message data is set automatically by the ICEMessagesDisplay
-    amcAutoProj,    // same as amcProj but the message data is set automatically from the widget side
+    amcAutoProj,    // same as amcProj but the message data is set automatically by the ICEMessagesDisplay
     amcAutoCompile  // same as amcAutoEdit or amcAutoProj, according to what's being compiled.
   );
 
@@ -267,7 +275,7 @@ type
    * Single service provided by the messages widget.
    *)
   ICEMessagesDisplay = interface(ICESingleService)
-    // displays a message
+    // displays a message.
     procedure message(const aValue: string; aData: Pointer; aCtxt: TCEAppMessageCtxt; aKind: TCEAppMessageKind);
     // clears the messages related to the context aCtxt.
     procedure clearByContext(aCtxt: TCEAppMessageCtxt);
@@ -285,7 +293,7 @@ type
     procedure addProcess(aProcess: TProcess);
     // removes an entry.
     procedure removeProcess(aProcess: TProcess);
-    // indicates the current process
+    // indicates the current process.
     function process: TProcess;
   end;
 
@@ -295,48 +303,49 @@ type
    * Single service related to the documents as a collection.
    *)
   ICEMultiDocHandler = interface(ICESingleService)
-    // returns the count of opened document
+    // returns the count of opened document.
     function documentCount: Integer;
-    // returns the nth document
+    // returns the nth document.
     function getDocument(index: Integer): TCESynMemo;
     // returns true if the document matching aFilename is already opened.
     function findDocument(aFilename: string): TCESynMemo;
-    // open or set the focus on the document matching aFilename
+    // opens or set the focus on the document matching aFilename.
     procedure openDocument(aFilename: string);
-    // close the nth document
+    // closes the nth document.
     function closeDocument(index: Integer): boolean;
-    // close a particular document
+    // closes a particular document.
     function closeDocument(doc: TCESynMemo): boolean;
-    // conveniance property
+    // conveniance property.
     property document[index: integer]: TCESynMemo read getDocument;
   end;
 
 
+
   (**
    * Single service related to the project groups
    *)
   ICEProjectGroup = interface(ICESingleService)
-    // add a project to the gtoup;
+    // adds a project to the gtoup.
     procedure addProject(aProject: ICECommonProject);
-    // open a group of project.
+    // opens a group of project.
     procedure openGroup(const fname: string);
-    // save the group to a file.
+    // saves the group to a file.
     procedure saveGroup(const fname: string);
-    // close a group a initialize a new one
+    // closes a group a initialize a new one.
     procedure closeGroup;
-    // indicates wether one of the project is modified or if the group is changed
+    // indicates wether one of the project is modified or if the group is changed.
     function groupModified: boolean;
-    // indicates the group filename
+    // indicates the group filename.
     function groupFilename: string;
-    // indicates the count of project in the group
+    // indicates the count of project in the group.
     function projectCount: integer;
-    // indicates the index of the project
+    // indicates the index of the project.
     function getProjectIndex: integer;
-    // returns the nth project
+    // returns the nth project.
     function getProject(index: Integer): ICECommonProject;
     // tries to find the project named fname.
     function findProject(const fname: string): ICECommonProject;
-    // selects the nth project
+    // selects the nth project of the group.
     procedure setProjectIndex(index: Integer);
   end;
 
@@ -346,7 +355,7 @@ type
    * Single service related to the expansion of Coedit "symbolic strings".
    *)
   ICESymStringExpander = interface(ICESingleService)
-    // expand all the symbols <IDENT> in value in result.
+    // expands all the symbols <IDENT> of value in result.
     function expand(const value: string): string;
   end;
 
@@ -355,7 +364,9 @@ type
    * Single service related to build-in file explorer.
    *)
   ICEExplorer = interface(ICESingleService)
+    // expands the explorer to the folder "location".
     procedure browse(const location: string);
+    // returns current folder.
     function currentLocation: string;
   end;
 
@@ -406,7 +417,7 @@ var
   i: Integer;
 begin
   with aSubject do for i:= 0 to fObservers.Count-1 do
-    (fObservers[i] as ICEMultiDocObserver).docNew(aDoc);
+    (fObservers[i] as ICEDocumentObserver).docNew(aDoc);
 end;
 
 procedure subjDocClosing(aSubject: TCEMultiDocSubject; aDoc: TCESynMemo);
@@ -414,7 +425,7 @@ var
   i: Integer;
 begin
   with aSubject do for i:= 0 to fObservers.Count-1 do
-    (fObservers[i] as ICEMultiDocObserver).docClosing(aDoc);
+    (fObservers[i] as ICEDocumentObserver).docClosing(aDoc);
 end;
 
 procedure subjDocFocused(aSubject: TCEMultiDocSubject; aDoc: TCESynMemo);
@@ -422,7 +433,7 @@ var
   i: Integer;
 begin
   with aSubject do for i:= 0 to fObservers.Count-1 do
-    (fObservers[i] as ICEMultiDocObserver).docFocused(aDoc);
+    (fObservers[i] as ICEDocumentObserver).docFocused(aDoc);
 end;
 
 procedure subjDocChanged(aSubject: TCEMultiDocSubject; aDoc: TCESynMemo);
@@ -430,7 +441,7 @@ var
   i: Integer;
 begin
   with aSubject do for i:= 0 to fObservers.Count-1 do
-    (fObservers[i] as ICEMultiDocObserver).docChanged(aDoc);
+    (fObservers[i] as ICEDocumentObserver).docChanged(aDoc);
 end;
 {$ENDREGION}
 

src/ce_libman.pas

@@ -62,7 +62,7 @@ type
     property libFile: string read fLibFile write setLibFile;
     property libProject: string read fLibProject write setLibProject;
     property enabled: boolean read fEnabled write fEnabled default true;
-    // TODO-cmaintenance: remove this property from 3 update 1
+    // TODO-cmaintenance: remove this property from version 3 update 1
     property projectFile: string read fLibProject write fLibProject stored false;
   public
     constructor Create(ACollection: TCollection); override;

src/ce_main.pas

@@ -26,7 +26,7 @@ type
   end;
 
   { TCEMainForm }
-  TCEMainForm = class(TForm, ICEMultiDocObserver, ICEEditableShortCut, ICEProjectObserver)
+  TCEMainForm = class(TForm, ICEDocumentObserver, ICEEditableShortCut, ICEProjectObserver)
     actFileCompAndRun: TAction;
     actFileSaveAll: TAction;
     actFileClose: TAction;
@@ -322,7 +322,7 @@ type
     procedure clearActProviderEntries;
     procedure collectedActProviderEntries;
 
-    // ICEMultiDocObserver
+    // ICEDocumentObserver
     procedure docNew(aDoc: TCESynMemo);
     procedure docClosing(aDoc: TCESynMemo);
     procedure docFocused(aDoc: TCESynMemo);

src/ce_messages.pas

@@ -58,7 +58,7 @@ type
 
   { TCEMessagesWidget }
 
-  TCEMessagesWidget = class(TCEWidget, ICEEditableOptions, ICEMultiDocObserver, ICEProjectObserver, ICEMessagesDisplay)
+  TCEMessagesWidget = class(TCEWidget, ICEEditableOptions, ICEDocumentObserver, ICEProjectObserver, ICEMessagesDisplay)
     btnSelAll: TCEToolButton;
     btnSelApp: TCEToolButton;
     btnSelEdit: TCEToolButton;
@@ -684,7 +684,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEMessagesWidget.docNew(aDoc: TCESynMemo);
 begin
 

src/ce_miniexplorer.pas

@@ -60,7 +60,7 @@ type
 
   { TCEMiniExplorerWidget }
 
-  TCEMiniExplorerWidget = class(TCEWidget, ICEProjectObserver, ICEMultiDocObserver, ICEExplorer)
+  TCEMiniExplorerWidget = class(TCEWidget, ICEProjectObserver, ICEDocumentObserver, ICEExplorer)
     btnAddFav: TCEToolButton;
     btnEdit: TCEToolButton;
     btnRemFav: TCEToolButton;
@@ -348,7 +348,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultidocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEMiniExplorerWidget.docNew(aDoc: TCESynMemo);
 begin
 end;

src/ce_mru.pas

@@ -44,9 +44,9 @@ type
 
   (**
    * MRU list for D/text files.
-   * Insertion is automatic (ICEMultiDocObserver).
+   * Insertion is automatic (ICEDocumentObserver).
    *)
-  TCEMRUDocumentList = class(TCEMRUFileList, ICEMultiDocObserver)
+  TCEMRUDocumentList = class(TCEMRUFileList, ICEDocumentObserver)
   private
     procedure docNew(aDoc: TCESynMemo);
     procedure docFocused(aDoc: TCESynMemo);

src/ce_search.pas

@@ -43,7 +43,7 @@ type
   end;
 
   { TCESearchWidget }
-  TCESearchWidget = class(TCEWidget, ICEMultiDocObserver, ICEProjectObserver)
+  TCESearchWidget = class(TCEWidget, ICEDocumentObserver, ICEProjectObserver)
     btnAllScope: TBitBtn;
     btnFind: TBitBtn;
     btnFindAll: TBitBtn;
@@ -488,7 +488,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCESearchWidget.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_staticmacro.pas

@@ -43,10 +43,10 @@ type
    * Erroneous insertion is avoided because in D '$' is either followed
    * by a symbol: '$-1', '$]' or by a blank '$ ]'
    *
-   * Shift + SPACE works automatically on the right editor (ICEMultiDocObserver)
+   * Shift + SPACE works automatically on the right editor (ICEDocumentObserver)
    * Automatic insertion is handled in TCESynMemo.KeyUp()
    *)
-  TCEStaticEditorMacro = class(TWritableLfmTextComponent, ICEMultiDocObserver, ICEEditableOptions, ICEEditableShortCut)
+  TCEStaticEditorMacro = class(TWritableLfmTextComponent, ICEDocumentObserver, ICEEditableOptions, ICEEditableShortCut)
   private
     fValidator: TRegExpr;
     fCompletor: TSynAutoComplete;
@@ -59,7 +59,7 @@ type
     procedure addDefaults;
     procedure updateCompletor;
     procedure setMacros(aValue: TStringList);
-    // ICEMultiDocObserver
+    // ICEDocumentObserver
     procedure docNew(aDoc: TCESynMemo);
     procedure docFocused(aDoc: TCESynMemo);
     procedure docChanged(aDoc: TCESynMemo);
@@ -252,7 +252,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCEStaticEditorMacro.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_symlist.pas

@@ -105,7 +105,7 @@ type
 
   { TCESymbolListWidget }
 
-  TCESymbolListWidget = class(TCEWidget, ICEMultiDocObserver, ICEEditableOptions)
+  TCESymbolListWidget = class(TCEWidget, ICEDocumentObserver, ICEEditableOptions)
     btnRefresh: TCEToolButton;
     imgList: TImageList;
     Tree: TTreeView;
@@ -500,7 +500,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCESymbolListWidget.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_symstring.pas

@@ -25,7 +25,7 @@ type
    * TCESymbolExpander is designed to expand Coedit symbolic strings,
    * using the information collected from several observer interfaces.
    *)
-  TCESymbolExpander = class(ICEMultiDocObserver, ICEProjectObserver, ICESymStringExpander)
+  TCESymbolExpander = class(ICEDocumentObserver, ICEProjectObserver, ICESymStringExpander)
   private
     fProj: TCENativeProject;
     fProjInterface: ICECommonProject;
@@ -135,7 +135,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCESymbolExpander.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;

src/ce_todolist.pas

@@ -75,7 +75,7 @@ type
 
   { TCETodoListWidget }
 
-  TCETodoListWidget = class(TCEWidget, ICEMultiDocObserver, ICEProjectObserver, ICEEditableOptions)
+  TCETodoListWidget = class(TCEWidget, ICEDocumentObserver, ICEProjectObserver, ICEEditableOptions)
     btnGo: TCEToolButton;
     btnRefresh: TCEToolButton;
     lstItems: TListView;
@@ -93,7 +93,7 @@ type
     fTodos: TTodoItems;
     fMsgs: ICEMessagesDisplay;
     fOptions: TCETodoOptions;
-    // ICEMultiDocObserver
+    // ICEDocumentObserver
     procedure docNew(aDoc: TCESynMemo);
     procedure docFocused(aDoc: TCESynMemo);
     procedure docChanged(aDoc: TCESynMemo);
@@ -314,7 +314,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultiDocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCETodoListWidget.docNew(aDoc: TCESynMemo);
 begin
 end;

src/ce_tools.pas

@@ -72,7 +72,7 @@ type
     function findTool(const value: string): TCEToolItem;
   end;
 
-  TCETools = class(TWritableLfmTextComponent, ICEMainMenuProvider, ICEEditableShortcut, ICEMultiDocObserver)
+  TCETools = class(TWritableLfmTextComponent, ICEMainMenuProvider, ICEEditableShortcut, ICEDocumentObserver)
   private
     fTools: TCEToolItems;
     fShctCount: Integer;
@@ -392,7 +392,7 @@ begin
 end;
 {$ENDREGION}
 
-{$REGION ICEMultidocObserver ---------------------------------------------------}
+{$REGION ICEDocumentObserver ---------------------------------------------------}
 procedure TCETools.docNew(aDoc: TCESynMemo);
 begin
   fDoc := aDoc;