Free cookie consent management tool by TermsFeed Policy Generator

Ignore:
Timestamp:
11/19/08 12:12:39 (16 years ago)
Author:
vdorfer
Message:

Created API documentation for HeuristicLab.Core namespace (#331)

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/sources/HeuristicLab.Core/OperatorBase.cs

    r76 r776  
    2626
    2727namespace HeuristicLab.Core {
     28  /// <summary>
     29  /// The base class for all operators.
     30  /// </summary>
    2831  public abstract class OperatorBase : ConstrainedItemBase, IOperator {
    2932    private string myName;
     33    /// <summary>
     34    /// Gets or sets the name of the operator.
     35    /// </summary>
     36    /// <remarks>Calls <see cref="OnNameChanged"/> in the setter.</remarks>
    3037    public string Name {
    3138      get { return myName; }
    … …  
    3744      }
    3845    }
     46    /// <summary>
     47    /// Gets the description of the current operator.
     48    /// </summary>
     49    /// <remarks>Returns "No operator description available" if the method is not overriden.</remarks>
    3950    public virtual string Description {
    4051      get { return "No operator description available."; }
    4152    }
    42 
     53    /// <summary>
     54    /// Flag whether the current instance has been canceled.
     55    /// </summary>
    4356    protected bool myCanceled;
     57    /// <inheritdoc/>
    4458    public bool Canceled {
    4559      get { return myCanceled; }
    4660    }
    4761    private bool myBreakpoint;
     62    /// <inheritdoc/>
     63    /// <remarks>Calls <see cref="OnBreakpointChanged"/> in the setter.</remarks>
    4864    public bool Breakpoint {
    4965      get { return myBreakpoint; }
    … …  
    5773
    5874    private List<IOperator> mySubOperators;
     75    /// <summary>
     76    /// Gets a list of all suboperators.
     77    /// <note type="caution"> Returns the suboperators read-only!</note>
     78    /// </summary>
    5979    public virtual IList<IOperator> SubOperators {
    6080      get { return mySubOperators.AsReadOnly(); }
    6181    }
    6282    private Dictionary<string, IVariableInfo> myVariableInfos;
     83    /// <inheritdoc/>
    6384    public virtual ICollection<IVariableInfo> VariableInfos {
    6485      get { return myVariableInfos.Values; }
    6586    }
    6687    private Dictionary<string, IVariable> myVariables;
     88    /// <inheritdoc/>
    6789    public virtual ICollection<IVariable> Variables {
    6890      get { return myVariables.Values; }
    6991    }
    7092
     93    /// <summary>
     94    /// Initializes a new instance of <see cref="OperatorBase"/> setting the breakpoint flag and
     95    /// the canceled flag to <c>false</c> and the name of the operator to the type name.
     96    /// </summary>
    7197    protected OperatorBase() {
    7298      myName = this.GetType().Name;
    … …  
    78104    }
    79105
     106    /// <summary>
     107    /// Clones the current instance (deep clone).
     108    /// </summary>
     109    /// <remarks>Clones also sub operators, variables and variable infos.</remarks>
     110    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
     111    /// <returns>The cloned object as <see cref="OperatorBase"/>.</returns>
    80112    public override object Clone(IDictionary<Guid, object> clonedObjects) {
    81113      OperatorBase clone = (OperatorBase)base.Clone(clonedObjects);
    … …  
    93125    }
    94126
     127    /// <summary>
     128    /// Creates a new instance of <see cref="OperatorBaseView"/> to represent the current operator
     129    /// visually.
     130    /// </summary>
     131    /// <returns>The created view as <see cref="OperatorBaseView"/>.</returns>
    95132    public override IView CreateView() {
    96133      return new OperatorBaseView(this);
    … …  
    98135
    99136    #region SubOperator Methods
     137    /// <inheritdoc cref="HeuristicLab.Core.IOperator.AddSubOperator(HeuristicLab.Core.IOperator)"/>
     138    /// <param name="subOperator">The sub operator to add.</param>
     139    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    100140    public virtual void AddSubOperator(IOperator subOperator) {
    101141      mySubOperators.Add(subOperator);
    102142      OnSubOperatorAdded(subOperator, mySubOperators.Count - 1);
    103143    }
     144    /// <inheritdoc cref="IOperator.TryAddSubOperator(HeuristicLab.Core.IOperator)"/>
     145    /// <param name="subOperator">The sub operator to add.</param>
     146    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    104147    public virtual bool TryAddSubOperator(IOperator subOperator) {
    105148      mySubOperators.Add(subOperator);
    … …  
    112155      }
    113156    }
     157    /// <inheritdoc cref="HeuristicLab.Core.IOperator.TryAddSubOperator(HeuristicLab.Core.IOperator,
     158    /// out System.Collections.Generic.ICollection&lt;HeuristicLab.Core.IConstraint&gt;)"/>
     159    /// <param name="subOperator">The sub operator to add.</param>
     160    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    114161    public virtual bool TryAddSubOperator(IOperator subOperator, out ICollection<IConstraint> violatedConstraints) {
    115162      mySubOperators.Add(subOperator);
    … …  
    122169      }
    123170    }
     171    /// <inheritdoc cref="HeuristicLab.Core.IOperator.AddSubOperator(HeuristicLab.Core.IOperator, int)"/>
     172    /// <param name="subOperator">The sub operator to add.</param>
     173    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    124174    public virtual void AddSubOperator(IOperator subOperator, int index) {
    125175      mySubOperators.Insert(index, subOperator);
    126176      OnSubOperatorAdded(subOperator, index);
    127177    }
     178    /// <inheritdoc cref="IOperator.TryAddSubOperator(HeuristicLab.Core.IOperator, int)"/>
     179    /// <param name="subOperator">The sub operator to add.</param>
     180    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    128181    public virtual bool TryAddSubOperator(IOperator subOperator, int index) {
    129182      mySubOperators.Insert(index, subOperator);
    … …  
    136189      }
    137190    }
     191    /// <inheritdoc cref="IOperator.TryAddSubOperator(HeuristicLab.Core.IOperator, int, out
     192    /// System.Collections.Generic.ICollection&lt;HeuristicLab.Core.IConstraint&gt;)"/>
     193    /// <param name="subOperator">The sub operator to add.</param>
     194    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    138195    public virtual bool TryAddSubOperator(IOperator subOperator, int index, out ICollection<IConstraint> violatedConstraints) {
    139196      mySubOperators.Insert(index, subOperator);
    … …  
    146203      }
    147204    }
     205    /// <inheritdoc/>
     206    /// <remarks>Calls <see cref="OnSubOperatorRemoved"/>.</remarks>
    148207    public virtual void RemoveSubOperator(int index) {
    149208      IOperator op = mySubOperators[index];
    … …  
    151210      OnSubOperatorRemoved(op, index);
    152211    }
     212    /// <inheritdoc/>
     213    /// <remarks>Calls <see cref="OnSubOperatorRemoved"/>.</remarks>
    153214    public virtual bool TryRemoveSubOperator(int index) {
    154215      IOperator op = mySubOperators[index];
    … …  
    162223      }
    163224    }
     225    /// <inheritdoc/>
     226    /// <remarks>Calls <see cref="OnSubOperatorRemoved"/>.</remarks>
    164227    public virtual bool TryRemoveSubOperator(int index, out ICollection<IConstraint> violatedConstraints) {
    165228      IOperator op = mySubOperators[index];
    … …  
    176239
    177240    #region VariableInfo Methods
     241    /// <inheritdoc/>
    178242    public virtual IVariableInfo GetVariableInfo(string formalName) {
    179243      IVariableInfo info;
    … …  
    183247        return null;
    184248    }
     249    /// <inheritdoc/>
     250    /// <remarks>Calls <see cref="OnVariableInfoAdded"/>.</remarks>
    185251    public virtual void AddVariableInfo(IVariableInfo variableInfo) {
    186252      myVariableInfos.Add(variableInfo.FormalName, variableInfo);
    187253      OnVariableInfoAdded(variableInfo);
    188254    }
     255    /// <inheritdoc/>
     256    /// <remarks>Calls <see cref="OnVariableInfoAdded"/>.</remarks>
    189257    public virtual bool TryAddVariableInfo(IVariableInfo variableInfo) {
    190258      myVariableInfos.Add(variableInfo.FormalName, variableInfo);
    … …  
    197265      }
    198266    }
     267    /// <inheritdoc/>
     268    /// <remarks>Calls <see cref="OnVariableInfoAdded"/>.</remarks>
    199269    public virtual bool TryAddVariableInfo(IVariableInfo variableInfo, out ICollection<IConstraint> violatedConstraints) {
    200270      myVariableInfos.Add(variableInfo.FormalName, variableInfo);
    … …  
    207277      }
    208278    }
     279    /// <inheritdoc/>
     280    /// <remarks>Calls <see cref="OnVariableInfoRemoved"/>.</remarks>
    209281    public virtual void RemoveVariableInfo(string formalName) {
    210282      IVariableInfo variableInfo;
    … …  
    214286      }
    215287    }
     288    /// <inheritdoc/>
     289    /// <remarks>Calls <see cref="OnVariableInfoRemoved"/>.</remarks>
    216290    public virtual bool TryRemoveVariableInfo(string formalName) {
    217291      IVariableInfo variableInfo;
    … …  
    228302      return true;
    229303    }
     304    /// <inheritdoc/>
     305    /// <remarks>Calls <see cref="OnVariableInfoRemoved"/>.</remarks>
    230306    public virtual bool TryRemoveVariableInfo(string formalName, out ICollection<IConstraint> violatedConstraints) {
    231307      IVariableInfo variableInfo;
    … …  
    246322
    247323    #region Variable Methods
     324    /// <inheritdoc/>
    248325    public virtual IVariable GetVariable(string name) {
    249326      IVariable variable;
    … …  
    253330        return null;
    254331    }
     332    /// <inheritdoc/>
     333    /// <remarks>Calls <see cref="OnVariableAdded"/> and adds <c>NameChanging</c> and <c>NameChanged</c>
     334    /// event handlers.</remarks>
    255335    public virtual void AddVariable(IVariable variable) {
    256336      myVariables.Add(variable.Name, variable);
    … …  
    259339      OnVariableAdded(variable);
    260340    }
     341    /// <inheritdoc/>
     342    /// <remarks>Calls <see cref="OnVariableAdded"/> and adds <c>NameChanging</c> and <c>NameChanged</c>
     343    /// event handlers.</remarks>
    261344    public virtual bool TryAddVariable(IVariable variable) {
    262345      myVariables.Add(variable.Name, variable);
    … …  
    271354      }
    272355    }
     356    /// <inheritdoc/>
     357    /// <remarks>Calls <see cref="OnVariableAdded"/> and adds <c>NameChanging</c> and <c>NameChanged</c>
     358    /// event handlers.</remarks>
    273359    public virtual bool TryAddVariable(IVariable variable, out ICollection<IConstraint> violatedConstraints) {
    274360      myVariables.Add(variable.Name, variable);
    … …  
    283369      }
    284370    }
     371    /// <inheritdoc/>
     372    /// <remarks>Calls <see cref="OnVariableRemoved"/> and removes <c>NameChanging</c> and <c>NameChanged</c>
     373    /// event handlers.</remarks>
    285374    public virtual void RemoveVariable(string name) {
    286375      IVariable variable;
    … …  
    292381      }
    293382    }
     383    /// <inheritdoc/>
     384    /// <remarks>Calls <see cref="OnVariableRemoved"/> and removes <c>NameChanging</c> and <c>NameChanged</c>
     385    /// event handlers.</remarks>
    294386    public virtual bool TryRemoveVariable(string name) {
    295387      IVariable variable;
    … …  
    308400      return true;
    309401    }
     402    /// <inheritdoc/>
     403    /// <remarks>Calls <see cref="OnVariableRemoved"/> and removes <c>NameChanging</c> and <c>NameChanged</c>
     404    /// event handlers.</remarks>
    310405    public virtual bool TryRemoveVariable(string name, out ICollection<IConstraint> violatedConstraints) {
    311406      IVariable variable;
    … …  
    338433      myVariables.Add(variable.Name, variable);
    339434    }
     435    /// <inheritdoc cref="IOperator.GetVariableValue&lt;T&gt;(string, HeuristicLab.Core.IScope, bool)"/>
     436    ///  <remarks>Calls <see cref="GetVariableValue&lt;T&gt;(string, HeuristicLab.Core.IScope, bool, bool)"/>
     437    /// with <c>throwOnError</c> set to <c>false</c>.</remarks>
    340438    public T GetVariableValue<T>(string formalName, IScope scope, bool recursiveLookup) where T : class, IItem {
    341439      return GetVariableValue<T>(formalName, scope, recursiveLookup, true);
    342440    }
     441    /// <inheritdoc cref="IOperator.GetVariableValue&lt;T&gt;(string, HeuristicLab.Core.IScope, bool, bool)"/>
     442    /// <remarks>Calls
     443    /// <see cref="GetVariableValue(string, HeuristicLab.Core.IScope, bool, bool)"/>.</remarks>
    343444    public T GetVariableValue<T>(string formalName, IScope scope, bool recursiveLookup, bool throwOnError) where T : class, IItem {
    344445      return (T)GetVariableValue(formalName, scope, recursiveLookup, throwOnError);
    345446    }
     447    /// <inheritdoc cref="IOperator.GetVariableValue(string, HeuristicLab.Core.IScope, bool)"/>
     448    /// <remarks>Calls <see cref="GetVariableValue(string, HeuristicLab.Core.IScope, bool, bool)"/>
     449    /// with <c>throwOnError</c> set to <c>false</c>.</remarks>
    346450    public IItem GetVariableValue(string formalName, IScope scope, bool recursiveLookup) {
    347451      return GetVariableValue(formalName, scope, recursiveLookup, true);
    348452    }
     453    /// <inheritdoc cref="IOperator.GetVariableValue(string, HeuristicLab.Core.IScope, bool, bool)"/>
    349454    public virtual IItem GetVariableValue(string formalName, IScope scope, bool recursiveLookup, bool throwOnError) {
    350455      IVariableInfo info = GetVariableInfo(formalName);
    … …  
    364469    }
    365470    #endregion
    366 
     471    /// <inheritdoc/>
    367472    public virtual IOperation Execute(IScope scope) {
    368473      myCanceled = false;
    … …  
    379484      return next;
    380485    }
     486    /// <inheritdoc/>
     487    /// <remarks>Sets property <see cref="Canceled"/> to <c>true</c>.</remarks>
    381488    public virtual void Abort() {
    382489      myCanceled = true;
    383490    }
    384 
     491    /// <summary>
     492    /// Performs the current operator on the specified <paramref name="scope"/>.
     493    /// </summary>
     494    /// <param name="scope">The scope where to execute the operator</param>
     495    /// <returns><c>null</c>.</returns>
    385496    public virtual IOperation Apply(IScope scope) {
    386497      return null;
    387498    }
    388 
     499    /// <inheritdoc/>
    389500    public event EventHandler NameChanged;
     501    /// <summary>
     502    /// Fires a new <c>NameChanged</c> event.
     503    /// </summary>
    390504    protected virtual void OnNameChanged() {
    391505      if (NameChanged != null) {
    … …  
    393507      }
    394508    }
     509    /// <inheritdoc/>
    395510    public event EventHandler BreakpointChanged;
     511    /// <summary>
     512    /// Fires a new <c>BreakpointChanged</c> event.
     513    /// </summary>
    396514    protected virtual void OnBreakpointChanged() {
    397515      if (BreakpointChanged != null) {
    … …  
    399517      }
    400518    }
     519    /// <inheritdoc/>
    401520    public event EventHandler<OperatorIndexEventArgs> SubOperatorAdded;
     521    /// <summary>
     522    /// Fires a new <c>SubOperatorAdded</c> event.
     523    /// </summary>
     524    /// <param name="subOperator">The sub operator that has been added.</param>
     525    /// <param name="index">The position where the operator has been added.</param>
    402526    protected virtual void OnSubOperatorAdded(IOperator subOperator, int index) {
    403527      if (SubOperatorAdded != null)
    404528        SubOperatorAdded(this, new OperatorIndexEventArgs(subOperator, index));
    405529    }
     530    /// <inheritdoc/>
    406531    public event EventHandler<OperatorIndexEventArgs> SubOperatorRemoved;
     532    /// <summary>
     533    /// Fires a new <c>SubOperatorRemoved</c> event.
     534    /// </summary>
     535    /// <param name="subOperator">The sub operator that has been removed.</param>
     536    /// <param name="index">The position where the operator has been removed.</param>
    407537    protected virtual void OnSubOperatorRemoved(IOperator subOperator, int index) {
    408538      if (SubOperatorRemoved != null)
    409539        SubOperatorRemoved(this, new OperatorIndexEventArgs(subOperator, index));
    410540    }
     541    /// <inheritdoc/>
    411542    public event EventHandler<VariableInfoEventArgs> VariableInfoAdded;
     543    /// <summary>
     544    /// Fires a new <c>VariableInfoAdded</c> event.
     545    /// </summary>
     546    /// <param name="variableInfo">The variable info that has been added.</param>
    412547    protected virtual void OnVariableInfoAdded(IVariableInfo variableInfo) {
    413548      if (VariableInfoAdded != null)
    414549        VariableInfoAdded(this, new VariableInfoEventArgs(variableInfo));
    415550    }
     551    /// <inheritdoc/>
    416552    public event EventHandler<VariableInfoEventArgs> VariableInfoRemoved;
     553    /// <summary>
     554    /// Fires a new <c>VariableInfoRemoved</c> event.
     555    /// </summary>
     556    /// <param name="variableInfo">The variable info that has been removed.</param>
    417557    protected virtual void OnVariableInfoRemoved(IVariableInfo variableInfo) {
    418558      if (VariableInfoRemoved != null)
    419559        VariableInfoRemoved(this, new VariableInfoEventArgs(variableInfo));
    420560    }
     561    /// <inheritdoc/>
    421562    public event EventHandler<VariableEventArgs> VariableAdded;
     563    /// <summary>
     564    /// Fires a new <c>VariableAdded</c> event.
     565    /// </summary>
     566    /// <param name="variable">The variable that has been added.</param>
    422567    protected virtual void OnVariableAdded(IVariable variable) {
    423568      if (VariableAdded != null)
    424569        VariableAdded(this, new VariableEventArgs(variable));
    425570    }
     571    /// <inheritdoc/>
    426572    public event EventHandler<VariableEventArgs> VariableRemoved;
     573    /// <summary>
     574    /// Fires a new <c>VariableRemoved</c> event.
     575    /// </summary>
     576    /// <param name="variable">The variable that has been removed</param>
    427577    protected virtual void OnVariableRemoved(IVariable variable) {
    428578      if (VariableRemoved != null)
    429579        VariableRemoved(this, new VariableEventArgs(variable));
    430580    }
     581    /// <inheritdoc/>
    431582    public event EventHandler Executed;
     583    /// <summary>
     584    /// Fires a new <c>Executed</c> event.
     585    /// </summary>
    432586    protected virtual void OnExecuted() {
    433587      if (Executed != null) {
    … …  
    437591
    438592    #region Persistence Methods
     593    /// <summary>
     594    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
     595    /// </summary>
     596    /// <remarks>
     597    /// Calls <see cref="ConstrainedItemBase.GetXmlNode"/> of base class <see cref="ConstrainedItemBase"/>.
     598    /// <br/>A quick overview how the single elements of the current instance are saved:
     599    /// <list type="bullet">
     600    /// <item>
     601    /// <term>Name: </term>
     602    /// <description>Saved as an <see cref="XmlAttribute"/> with the name <c>Name</c>.</description>
     603    /// </item>
     604    /// <item>
     605    /// <term>Breakpoint: </term>
     606    /// <description>Is only saved if it set to <c>true</c>.
     607    /// Saved as an <see cref="XmlAttribute"/> with the name <c>Breakpoint</c>.</description>
     608    /// </item>
     609    /// <item>
     610    /// <term>Sub operators: </term>
     611    /// <description>Saved as child node with tag name <c>SubOperators</c>. All sub operators are themselves
     612    /// saved as child nodes.</description>
     613    /// </item>
     614    /// <item>
     615    /// <term>Variable infos: </term>
     616    /// <description>Saved as child node with tag name <c>VariableInfos</c>. All variable infos are themselves
     617    /// saved as child nodes.</description>
     618    /// </item>
     619    /// <item>
     620    /// <term>Variables: </term>
     621    /// <description>Saved as child node with tag name <c>Variables</c>. All variables are themselves
     622    /// saved as child nodes.</description>
     623    /// </item>
     624    /// </list>
     625    /// </remarks>
     626    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
     627    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
     628    /// <param name="persistedObjects">The dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
     629    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    439630    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid,IStorable> persistedObjects) {
    440631      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
    … …  
    461652      return node;
    462653    }
     654    /// <summary>
     655    /// Loads the persisted operation from the specified <paramref name="node"/>.
     656    /// </summary>
     657    /// <remarks>Calls <see cref="ConstrainedItemBase.Populate"/> of base class
     658    /// <see cref="ConstrainedItemBase"/>.
     659    /// For informations how the different elements must be saved please see <see cref="GetXmlNode"/>.</remarks>
     660    /// <param name="node">The <see cref="XmlNode"/> where the operation is saved.</param>
     661    /// <param name="restoredObjects">A dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    463662    public override void Populate(XmlNode node, IDictionary<Guid,IStorable> restoredObjects) {
    464663      base.Populate(node, restoredObjects);
Note: See TracChangeset for help on using the changeset viewer.