diff options
author | Lluis Sanchez <lluis@novell.com> | 2010-06-17 18:30:38 +0400 |
---|---|---|
committer | Lluis Sanchez <lluis@novell.com> | 2010-06-17 18:30:38 +0400 |
commit | 40d1bd1b5a14a1986b4c4318a8f642d4d95cf494 (patch) | |
tree | 886028ea9b90bf739312d818b7964c39eb366f84 | |
parent | 614a4708d76b1aeec1a0536776b3ef8c8cfbf6bb (diff) |
* Mono.Addins/Mono.Addins/NodeElement.cs:
* Mono.Addins/Mono.Addins/RuntimeAddin.cs:
* Mono.Addins/Mono.Addins/IProgressStatus.cs:
* Mono.Addins/Mono.Addins/IAddinInstaller.cs:
* Mono.Addins/Mono.Addins/TypeExtensionNode.cs:
* Mono.Addins/Mono.Addins/ExtensionNodeList.cs:
* Mono.Addins/Mono.Addins/InstanceExtensionNode.cs:
* Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs:
* Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs:
* Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs:
* Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs:
* Mono.Addins/Mono.Addins/MissingDependencyException.cs:
* Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs:
* Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs:
* Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs: Added some
documentation.
svn path=/trunk/mono-addins/; revision=159072
-rw-r--r-- | Mono.Addins/ChangeLog | 19 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs | 33 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs | 33 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ExtensionNodeList.cs | 36 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs | 54 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/IAddinInstaller.cs | 15 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/IProgressStatus.cs | 63 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs | 28 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs | 22 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/InstanceExtensionNode.cs | 41 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/MissingDependencyException.cs | 3 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs | 134 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/NodeElement.cs | 40 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/RuntimeAddin.cs | 231 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/TypeExtensionNode.cs | 36 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs | 30 |
16 files changed, 813 insertions, 5 deletions
diff --git a/Mono.Addins/ChangeLog b/Mono.Addins/ChangeLog index 357ca38..4f4d84d 100644 --- a/Mono.Addins/ChangeLog +++ b/Mono.Addins/ChangeLog @@ -1,3 +1,22 @@ +2010-06-17 Lluis Sanchez Gual <lluis@novell.com> + + * Mono.Addins/NodeElement.cs: + * Mono.Addins/RuntimeAddin.cs: + * Mono.Addins/IProgressStatus.cs: + * Mono.Addins/IAddinInstaller.cs: + * Mono.Addins/TypeExtensionNode.cs: + * Mono.Addins/ExtensionNodeList.cs: + * Mono.Addins/InstanceExtensionNode.cs: + * Mono.Addins/NodeAttributeAttribute.cs: + * Mono.Addins/ExtensionNodeAttribute.cs: + * Mono.Addins/ExtensionPointAttribute.cs: + * Mono.Addins/ImportAddinFileAttribute.cs: + * Mono.Addins/MissingDependencyException.cs: + * Mono.Addins/TypeExtensionPointAttribute.cs: + * Mono.Addins/ExtensionNodeChildAttribute.cs: + * Mono.Addins/ImportAddinAssemblyAttribute.cs: Added some + documentation. + 2010-05-27 Lluis Sanchez Gual <lluis@novell.com> * Mono.Addins/AddinManager.cs: diff --git a/Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs b/Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs index bf089a3..b53c99f 100644 --- a/Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs +++ b/Mono.Addins/Mono.Addins/ExtensionNodeAttribute.cs @@ -31,6 +31,12 @@ using System; namespace Mono.Addins { + /// <summary> + /// This attribute can be applied to an ExtensionNode subclass to specify the default name and description. + /// </summary> + /// <remarks> + /// This information will be used when an extension point does not define a name or description for a node type. + /// </remarks> [AttributeUsage (AttributeTargets.Class)] public class ExtensionNodeAttribute: Attribute { @@ -39,31 +45,58 @@ namespace Mono.Addins string customAttributeTypeName; Type customAttributeType; + /// <summary> + /// Initializes the attribute + /// </summary> public ExtensionNodeAttribute () { } + /// <summary> + /// Initializes the attribute + /// </summary> + /// <param name="nodeName"> + /// Name of the node + /// </param> public ExtensionNodeAttribute (string nodeName) { this.nodeName = nodeName; } + /// <summary> + /// Initializes the attribute + /// </summary> + /// <param name="nodeName"> + /// Name of the node + /// </param> + /// <param name="description"> + /// Description of the node + /// </param> public ExtensionNodeAttribute (string nodeName, string description) { this.nodeName = nodeName; this.description = description; } + /// <summary> + /// Default name of the extension node + /// </summary> public string NodeName { get { return nodeName != null ? nodeName : string.Empty; } set { nodeName = value; } } + /// <summary> + /// Default description of the extension node type + /// </summary> public string Description { get { return description != null ? description : string.Empty; } set { description = value; } } + /// <summary> + /// Type of a custom attribute which can be used to specify metadata for this extension node type + /// </summary> public Type ExtensionAttributeType { get { return customAttributeType; } set { customAttributeType = value; customAttributeTypeName = value.FullName; } diff --git a/Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs b/Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs index 66f8f1a..d5839e8 100644 --- a/Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs +++ b/Mono.Addins/Mono.Addins/ExtensionNodeChildAttribute.cs @@ -31,6 +31,12 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares allowed children of an extension node type. + /// </summary> + /// <remarks> + /// This attribute allows declaring the type of children that an extension node can have. + /// </remarks> [AttributeUsage (AttributeTargets.Class, AllowMultiple=true)] public class ExtensionNodeChildAttribute: Attribute { @@ -38,27 +44,54 @@ namespace Mono.Addins Type extensionNodeType; string extensionNodeTypeName; + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="nodeName"> + /// Name of the allowed child extension node. + /// </param> public ExtensionNodeChildAttribute (string nodeName) : this (typeof(TypeExtensionNode), nodeName) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="extensionNodeType"> + /// Type of the allowed child extension node. + /// </param> public ExtensionNodeChildAttribute (Type extensionNodeType) : this (extensionNodeType, null) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="extensionNodeType"> + /// Type of the allowed child extension node. + /// </param> + /// <param name="nodeName"> + /// Name of the allowed child extension node. + /// </param> public ExtensionNodeChildAttribute (Type extensionNodeType, string nodeName) { ExtensionNodeType = extensionNodeType; this.nodeName = nodeName; } + /// <summary> + /// Name of the allowed child extension node. + /// </summary> public string NodeName { get { return nodeName != null ? nodeName : string.Empty; } set { nodeName = value; } } + /// <summary> + /// Type of the allowed child extension node. + /// </summary> public Type ExtensionNodeType { get { return extensionNodeType; } set { extensionNodeType = value; extensionNodeTypeName = value.FullName; } diff --git a/Mono.Addins/Mono.Addins/ExtensionNodeList.cs b/Mono.Addins/Mono.Addins/ExtensionNodeList.cs index 6edcedc..de56426 100644 --- a/Mono.Addins/Mono.Addins/ExtensionNodeList.cs +++ b/Mono.Addins/Mono.Addins/ExtensionNodeList.cs @@ -33,6 +33,9 @@ using System.Collections.Generic; namespace Mono.Addins { + /// <summary> + /// A list of extension nodes. + /// </summary> public class ExtensionNodeList: IEnumerable { internal List<ExtensionNode> list; @@ -44,6 +47,12 @@ namespace Mono.Addins this.list = list; } + /// <summary> + /// Returns the node in the specified index. + /// </summary> + /// <param name="n"> + /// The index. + /// </param> public ExtensionNode this [int n] { get { if (list == null) @@ -53,6 +62,12 @@ namespace Mono.Addins } } + /// <summary> + /// Returns the node with the specified ID. + /// </summary> + /// <param name="id"> + /// An id. + /// </param> public ExtensionNode this [string id] { get { if (list == null) @@ -73,6 +88,9 @@ namespace Mono.Addins return list.GetEnumerator (); } + /// <summary> + /// Number of nodes of the collection. + /// </summary> public int Count { get { return list == null ? 0 : list.Count; } } @@ -84,6 +102,9 @@ namespace Mono.Addins } } + /// <summary> + /// A list of extension nodes. + /// </summary> public class ExtensionNodeList<T>: IEnumerable, IEnumerable<T> where T: ExtensionNode { List<ExtensionNode> list; @@ -95,6 +116,12 @@ namespace Mono.Addins this.list = list; } + /// <summary> + /// Returns the node in the specified index. + /// </summary> + /// <param name="n"> + /// The index. + /// </param> public T this [int n] { get { if (list == null) @@ -104,6 +131,12 @@ namespace Mono.Addins } } + /// <summary> + /// Returns the node with the specified ID. + /// </summary> + /// <param name="id"> + /// An id. + /// </param> public T this [string id] { get { if (list == null) @@ -132,6 +165,9 @@ namespace Mono.Addins return list.GetEnumerator (); } + /// <summary> + /// Number of nodes of the collection. + /// </summary> public int Count { get { return list == null ? 0 : list.Count; } } diff --git a/Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs b/Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs index a4bd4b5..7038ba0 100644 --- a/Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs +++ b/Mono.Addins/Mono.Addins/ExtensionPointAttribute.cs @@ -31,6 +31,9 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares an extension point. + /// </summary> [AttributeUsage (AttributeTargets.Assembly, AllowMultiple=true)] public class ExtensionPointAttribute: Attribute { @@ -45,21 +48,51 @@ namespace Mono.Addins Type customAttributeType; string customAttributeTypeName; + /// <summary> + /// Initializes a new instance + /// </summary> public ExtensionPointAttribute () { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="path"> + /// Extension path that identifies the extension point + /// </param> public ExtensionPointAttribute (string path) { this.path = path; } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="path"> + /// Extension path that identifies the extension point + /// </param> + /// <param name="nodeType"> + /// Type of the extension node to be created for extensions + /// </param> public ExtensionPointAttribute (string path, Type nodeType) { this.path = path; this.nodeType = nodeType; } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="path"> + /// Extension path that identifies the extension point + /// </param> + /// <param name="nodeName"> + /// Element name to be used when defining an extension in an XML manifest. + /// </param> + /// <param name="nodeType"> + /// Type of the extension node to be created for extensions + /// </param> public ExtensionPointAttribute (string path, string nodeName, Type nodeType) { this.path = path; @@ -67,21 +100,33 @@ namespace Mono.Addins this.nodeName = nodeName; } + /// <summary> + /// Extension path that identifies the extension point + /// </summary> public string Path { get { return path != null ? path : string.Empty; } set { path = value; } } + /// <summary> + /// Long description of the extension point. + /// </summary> public string Description { get { return desc != null ? desc : string.Empty; } set { desc = value; } } + /// <summary> + /// Type of the extension node to be created for extensions + /// </summary> public Type NodeType { get { return nodeType != null ? nodeType : typeof(TypeExtensionNode); } set { nodeType = value; nodeTypeName = value.FullName; } } + /// <summary> + /// Expected extension object type (when nodes are of type TypeExtensionNode) + /// </summary> public Type ObjectType { get { return objectType; } set { objectType = value; objectTypeName = value.FullName; } @@ -97,16 +142,25 @@ namespace Mono.Addins set { objectTypeName = value; } } + /// <summary> + /// Element name to be used when defining an extension in an XML manifest. The default name is "Type". + /// </summary> public string NodeName { get { return nodeName != null && nodeName.Length > 0 ? nodeName : string.Empty; } set { nodeName = value; } } + /// <summary> + /// Display name of the extension point. + /// </summary> public string Name { get { return name != null ? name : string.Empty; } set { name = value; } } + /// <summary> + /// Type of the custom attribute to be used to specify metadata for the extension point + /// </summary> public Type ExtensionAttributeType { get { return this.customAttributeType; } set { this.customAttributeType = value; customAttributeTypeName = value.FullName; } diff --git a/Mono.Addins/Mono.Addins/IAddinInstaller.cs b/Mono.Addins/Mono.Addins/IAddinInstaller.cs index 7dd3607..3b9b7d5 100644 --- a/Mono.Addins/Mono.Addins/IAddinInstaller.cs +++ b/Mono.Addins/Mono.Addins/IAddinInstaller.cs @@ -4,8 +4,23 @@ using System; namespace Mono.Addins { + /// <summary> + /// An add-in installation handler + /// </summary> public interface IAddinInstaller { + /// <summary> + /// Installs a set of add-ins + /// </summary> + /// <param name="reg"> + /// Registry where to install + /// </param> + /// <param name="message"> + /// Message to show to the user when new add-ins have to be installed. + /// </param> + /// <param name="addinIds"> + /// List of IDs of the add-ins to be installed. + /// </param> void InstallAddins (AddinRegistry reg, string message, string[] addinIds); } } diff --git a/Mono.Addins/Mono.Addins/IProgressStatus.cs b/Mono.Addins/Mono.Addins/IProgressStatus.cs index 834c739..48100aa 100644 --- a/Mono.Addins/Mono.Addins/IProgressStatus.cs +++ b/Mono.Addins/Mono.Addins/IProgressStatus.cs @@ -31,18 +31,79 @@ using System; namespace Mono.Addins { + /// <summary> + /// Progress status listener. + /// </summary> public interface IProgressStatus { + /// <summary> + /// Sets the description of the current operation. + /// </summary> + /// <param name="msg"> + /// A message + /// </param> + /// <remarks> + /// This method is called by the add-in engine to show a description of the operation being monitorized. + /// </remarks> void SetMessage (string msg); + + /// <summary> + /// Sets the progress of the operation. + /// </summary> + /// <param name="progress"> + /// A number between 0 and 1. 0 means no progress, 1 means operation completed. + /// </param> + /// <remarks> + /// This method is called by the add-in engine to show the progress of the operation being monitorized. + /// </remarks> void SetProgress (double progress); + /// <summary> + /// Writes text to the log. + /// </summary> + /// <param name="msg"> + /// Message to write + /// </param> void Log (string msg); - int LogLevel { get; } // 0: no log, 1: normal log, >1 verbose log + /// <summary> + /// Log level requested by the user: 0: no log, 1: normal log, >1 verbose log + /// </summary> + int LogLevel { get; } + + /// <summary> + /// Reports a warning. + /// </summary> + /// <param name="message"> + /// Warning message + /// </param> + /// <remarks> + /// This method is called by the add-in engine to report a warning in the operation being monitorized. + /// </remarks> void ReportWarning (string message); + + /// <summary> + /// Reports an error. + /// </summary> + /// <param name="message"> + /// Error message + /// </param> + /// <param name="exception"> + /// Exception that caused the error. It can be null. + /// </param> + /// <remarks> + /// This method is called by the add-in engine to report an error occurred while executing the operation being monitorized. + /// </remarks> void ReportError (string message, Exception exception); + /// <summary> + /// Returns True when the user requested to cancel this operation + /// </summary> bool IsCanceled { get; } + + /// <summary> + /// Cancels the operation being montorized. + /// </summary> void Cancel (); } } diff --git a/Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs b/Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs index 257b194..0e3bd6c 100644 --- a/Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs +++ b/Mono.Addins/Mono.Addins/ImportAddinAssemblyAttribute.cs @@ -23,24 +23,52 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. + using System; + namespace Mono.Addins { + /// <summary> + /// Declares an add-in assembly import + /// </summary> + /// <remarks> + /// An add-in may be composed by several assemblies and data files. + /// Assemblies must be declared in the main assembly using this attribute, or in the XML manifest. + /// + /// It is important to properly declare all files used by an add-in. + /// For example, when a type from the add-in is required (e.g. an ICommand implementation), + /// only properly declared assemblies will be checked. + /// This information is also used by setup tools to know exactly what needs to be packaged when creating + /// an add-in package, or to know what needs to be deleted when removing an add-in. + /// </remarks> public class ImportAddinAssemblyAttribute: Attribute { string filePath; bool scan = true; + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="filePath"> + /// Path to the assembly. Must be relative to the assembly declaring this attribute. + /// </param> public ImportAddinAssemblyAttribute (string filePath) { this.filePath = filePath; } + /// <summary> + /// Path to the assembly. Must be relative to the assembly declaring this attribute. + /// </summary> public string FilePath { get { return filePath; } set { filePath = value; } } + /// <summary> + /// When set to true (the default), the included assembly will be scanned + /// looking for extension point declarations. + /// </summary> public bool Scan { get { return this.scan; } set { this.scan = value; } diff --git a/Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs b/Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs index 79a3c19..15607fd 100644 --- a/Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs +++ b/Mono.Addins/Mono.Addins/ImportAddinFileAttribute.cs @@ -23,18 +23,40 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. + using System; + namespace Mono.Addins { + /// <summary> + /// Declares an add-in file import + /// </summary> + /// <remarks> + /// An add-in may be composed by several assemblies and data files. + /// Data files must be declared in the main assembly using this attribute, or in the XML manifest. + /// + /// It is important to properly declare all files used by an add-in. + /// This information is used by setup tools to know exactly what needs to be packaged when creating + /// an add-in package, or to know what needs to be deleted when removing an add-in. + /// </remarks> public class ImportAddinFileAttribute: Attribute { string filePath; + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="filePath"> + /// Path to the file. Must be relative to the assembly declaring this attribute. + /// </param> public ImportAddinFileAttribute (string filePath) { this.filePath = filePath; } + /// <summary> + /// Path to the file. Must be relative to the assembly declaring this attribute. + /// </summary> public string FilePath { get { return filePath; } set { filePath = value; } diff --git a/Mono.Addins/Mono.Addins/InstanceExtensionNode.cs b/Mono.Addins/Mono.Addins/InstanceExtensionNode.cs index 5d7afc6..3d6640d 100644 --- a/Mono.Addins/Mono.Addins/InstanceExtensionNode.cs +++ b/Mono.Addins/Mono.Addins/InstanceExtensionNode.cs @@ -31,10 +31,25 @@ using System; namespace Mono.Addins { + /// <summary> + /// Base class for extension nodes which create extension objects + /// </summary> public abstract class InstanceExtensionNode: ExtensionNode { object cachedInstance; + /// <summary> + /// Gets the extension object declared by this node + /// </summary> + /// <param name="expectedType"> + /// Expected object type. An exception will be thrown if the object is not an instance of the specified type. + /// </param> + /// <returns> + /// The extension object + /// </returns> + /// <remarks> + /// The extension object is cached and the same instance will be returned at every call. + /// </remarks> public object GetInstance (Type expectedType) { object ob = GetInstance (); @@ -43,13 +58,31 @@ namespace Mono.Addins return ob; } + /// <summary> + /// Gets the extension object declared by this node + /// </summary> + /// <returns> + /// The extension object + /// </returns> + /// <remarks> + /// The extension object is cached and the same instance will be returned at every call. + /// </remarks> public object GetInstance () { if (cachedInstance == null) cachedInstance = CreateInstance (); return cachedInstance; } - + + /// <summary> + /// Creates a new extension object + /// </summary> + /// <param name="expectedType"> + /// Expected object type. An exception will be thrown if the object is not an instance of the specified type. + /// </param> + /// <returns> + /// The extension object + /// </returns> public object CreateInstance (Type expectedType) { object ob = CreateInstance (); @@ -58,6 +91,12 @@ namespace Mono.Addins return ob; } + /// <summary> + /// Creates a new extension object + /// </summary> + /// <returns> + /// The extension object + /// </returns> public abstract object CreateInstance (); } } diff --git a/Mono.Addins/Mono.Addins/MissingDependencyException.cs b/Mono.Addins/Mono.Addins/MissingDependencyException.cs index 4680c63..912aad2 100644 --- a/Mono.Addins/Mono.Addins/MissingDependencyException.cs +++ b/Mono.Addins/Mono.Addins/MissingDependencyException.cs @@ -32,6 +32,9 @@ using System.Runtime.Serialization; namespace Mono.Addins { + /// <summary> + /// Exception thrown when the add-in engine can't find a required add-in dependency + /// </summary> [Serializable] internal class MissingDependencyException: Exception { diff --git a/Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs b/Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs index 4cf49e9..7e92a7b 100644 --- a/Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs +++ b/Mono.Addins/Mono.Addins/NodeAttributeAttribute.cs @@ -31,6 +31,9 @@ using System; namespace Mono.Addins { + /// <summary> + /// Indicates that a field or property is bound to a node attribute + /// </summary> [AttributeUsage (AttributeTargets.Class | AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Parameter, AllowMultiple=true)] public class NodeAttributeAttribute: Attribute { @@ -41,25 +44,64 @@ namespace Mono.Addins string typeName; string description; + /// <summary> + /// Initializes a new instance + /// </summary> public NodeAttributeAttribute () { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> public NodeAttributeAttribute (string name) :this (name, false, null) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="description"> + /// Description of the attribute. + /// </param> public NodeAttributeAttribute (string name, string description) :this (name, false, description) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="required"> + /// Indicates whether the attribute is required or not. + /// </param> public NodeAttributeAttribute (string name, bool required) : this (name, required, null) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="required"> + /// Indicates whether the attribute is required or not. + /// </param> + /// <param name="description"> + /// Description of the attribute. + /// </param> public NodeAttributeAttribute (string name, bool required, string description) { this.name = name; @@ -67,21 +109,85 @@ namespace Mono.Addins this.description = description; } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="type"> + /// Type of the extension node attribute. + /// </param> + /// <remarks> + /// The type of the attribute is only required when applying this attribute at class level. + /// It is not required when it is applied to a field, since the attribute type will be the type of the field. + /// </remarks> public NodeAttributeAttribute (string name, Type type) : this (name, type, false, null) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="type"> + /// Type of the extension node attribute. + /// </param> + /// <param name="description"> + /// Description of the attribute. + /// </param> + /// <remarks> + /// The type of the attribute is only required when applying this attribute at class level. + /// It is not required when it is applied to a field, since the attribute type will be the type of the field. + /// </remarks> public NodeAttributeAttribute (string name, Type type, string description) : this (name, type, false, description) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="type"> + /// Type of the extension node attribute. + /// </param> + /// <param name="required"> + /// Indicates whether the attribute is required or not. + /// </param> + /// <remarks> + /// The type of the attribute is only required when applying this attribute at class level. + /// It is not required when it is applied to a field, since the attribute type will be the type of the field. + /// </remarks> public NodeAttributeAttribute (string name, Type type, bool required) : this (name, type, false, null) { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="name"> + /// XML name of the attribute. + /// </param> + /// <param name="type"> + /// Type of the extension node attribute. + /// </param> + /// <param name="required"> + /// Indicates whether the attribute is required or not. + /// </param> + /// <param name="description"> + /// Description of the attribute. + /// </param> + /// <remarks> + /// The type of the attribute is only required when applying this attribute at class level. + /// It is not required when it is applied to a field, since the attribute type will be the type of the field. + /// </remarks> public NodeAttributeAttribute (string name, Type type, bool required, string description) { this.name = name; @@ -90,16 +196,34 @@ namespace Mono.Addins this.description = description; } + /// <summary> + /// XML name of the attribute. + /// </summary> + /// <remarks> + /// If the name is not specified, the field name to which the [NodeAttribute] + /// is applied will be used as name. Providing a name is mandatory when applying + /// [NodeAttribute] at class level. + /// </remarks> public string Name { get { return name != null ? name : string.Empty; } set { name = value; } } + /// <summary> + /// Indicates whether the attribute is required or not. + /// </summary> public bool Required { get { return required; } set { required = value; } } + /// <summary> + /// Type of the extension node attribute. + /// </summary> + /// <remarks> + /// To be used only when applying [NodeAttribute] at class level. It is not required when it + /// is applied to a field, since the attribute type will be the type of the field. + /// </remarks> public Type Type { get { return type; } set { type = value; typeName = type.FullName; } @@ -110,11 +234,21 @@ namespace Mono.Addins set { typeName = value; type = null; } } + /// <summary> + /// Description of the attribute. + /// </summary> + /// <remarks> + /// To be used in the extension point documentation. + /// </remarks> public string Description { get { return description != null ? description : string.Empty; } set { description = value; } } + /// <summary> + /// When set to True, the value of the field or property is expected to be a string id which + /// will be localized by the add-in engine + /// </summary> public bool Localizable { get { return localizable; } set { localizable = value; } diff --git a/Mono.Addins/Mono.Addins/NodeElement.cs b/Mono.Addins/Mono.Addins/NodeElement.cs index 4599482..e90dc4e 100644 --- a/Mono.Addins/Mono.Addins/NodeElement.cs +++ b/Mono.Addins/Mono.Addins/NodeElement.cs @@ -32,14 +32,45 @@ using System.Collections; namespace Mono.Addins { + /// <summary> + /// An extension node element. + /// </summary> + /// <remarks> + /// A raw representation of an extension node. Contains the basic information + /// needed to create ExtensionNode instances. + /// </remarks> public interface NodeElement { + /// <summary> + /// Name of the node element. + /// </summary> string NodeName { get; } + + /// <summary> + /// Gets element attributes. + /// </summary> + /// <param name="key"> + /// Name of the attribute + /// </param> + /// <returns> + /// The value of the attribute + /// </returns> string GetAttribute (string key); + + /// <summary> + /// Gets all attributes defined in the element. + /// </summary> NodeAttribute[] Attributes { get; } + + /// <summary> + /// Gets child nodes of this node + /// </summary> NodeElementCollection ChildNodes { get; } } + /// <summary> + /// Attribute of a NodeElement. + /// </summary> public class NodeAttribute { internal string name; @@ -49,15 +80,24 @@ namespace Mono.Addins { } + /// <summary> + /// Name of the attribute. + /// </summary> public string Name { get { return name; } } + /// <summary> + /// Value of the attribute. + /// </summary> public string Value { get { return value; } } } + /// <summary> + /// A collection of NodeElement objects + /// </summary> public interface NodeElementCollection: IList, ICollection, IEnumerable { new NodeElement this [int n] { get; } diff --git a/Mono.Addins/Mono.Addins/RuntimeAddin.cs b/Mono.Addins/Mono.Addins/RuntimeAddin.cs index 8babd42..bb4c89a 100644 --- a/Mono.Addins/Mono.Addins/RuntimeAddin.cs +++ b/Mono.Addins/Mono.Addins/RuntimeAddin.cs @@ -42,6 +42,9 @@ using Mono.Addins.Localization; namespace Mono.Addins { + /// <summary> + /// Run-time representation of an add-in. + /// </summary> public class RuntimeAddin { string id; @@ -82,10 +85,16 @@ namespace Mono.Addins } } + /// <summary> + /// Identifier of the add-in. + /// </summary> public string Id { get { return Addin.GetIdName (id); } } + /// <summary> + /// Version of the add-in. + /// </summary> public string Version { get { return Addin.GetIdVersion (id); } } @@ -119,31 +128,121 @@ namespace Mono.Addins return resourceManagers = (ResourceManager[]) managersList.ToArray (typeof(ResourceManager)); } + /// <summary> + /// Gets a resource string + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <returns> + /// The value of the resource string, or null if the resource can't be found. + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public string GetResourceString (string name) { return (string) GetResourceObject (name, true, null); } + /// <summary> + /// Gets a resource string + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <param name="throwIfNotFound"> + /// When set to true, an exception will be thrown if the resource is not found. + /// </param> + /// <returns> + /// The value of the resource string + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public string GetResourceString (string name, bool throwIfNotFound) { return (string) GetResourceObject (name, throwIfNotFound, null); } + /// <summary> + /// Gets a resource string + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <param name="throwIfNotFound"> + /// When set to true, an exception will be thrown if the resource is not found. + /// </param> + /// <param name="culture"> + /// Culture of the resource + /// </param> + /// <returns> + /// The value of the resource string + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public string GetResourceString (string name, bool throwIfNotFound, CultureInfo culture) { return (string) GetResourceObject (name, throwIfNotFound, culture); } + /// <summary> + /// Gets a resource object + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <returns> + /// Value of the resource + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public object GetResourceObject (string name) { return GetResourceObject (name, true, null); } + /// <summary> + /// Gets a resource object + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <param name="throwIfNotFound"> + /// When set to true, an exception will be thrown if the resource is not found. + /// </param> + /// <returns> + /// Value of the resource + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public object GetResourceObject (string name, bool throwIfNotFound) { return GetResourceObject (name, throwIfNotFound, null); } + /// <summary> + /// Gets a resource object + /// </summary> + /// <param name="name"> + /// Name of the resource + /// </param> + /// <param name="throwIfNotFound"> + /// When set to true, an exception will be thrown if the resource is not found. + /// </param> + /// <param name="culture"> + /// Culture of the resource + /// </param> + /// <returns> + /// Value of the resource + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public object GetResourceObject (string name, bool throwIfNotFound, CultureInfo culture) { // Look in resources of this add-in @@ -166,12 +265,45 @@ namespace Mono.Addins return null; } - + /// <summary> + /// Gets a type defined in the add-in + /// </summary> + /// <param name="typeName"> + /// Full name of the type + /// </param> + /// <returns> + /// A type. + /// </returns> + /// <remarks> + /// The type will be looked up in the assemblies that implement the add-in, + /// and recursivelly in all add-ins on which it depends. + /// + /// This method throws an InvalidOperationException if the type can't be found. + /// </remarks> public Type GetType (string typeName) { return GetType (typeName, true); } + /// <summary> + /// Gets a type defined in the add-in + /// </summary> + /// <param name="typeName"> + /// Full name of the type + /// </param> + /// <param name="throwIfNotFound"> + /// Indicates whether the method should throw an exception if the type can't be found. + /// </param> + /// <returns> + /// A <see cref="Type"/> + /// </returns> + /// <remarks> + /// The type will be looked up in the assemblies that implement the add-in, + /// and recursivelly in all add-ins on which it depends. + /// + /// If the type can't be found, this method throw a InvalidOperationException if + /// 'throwIfNotFound' is 'true', or 'null' otherwise. + /// </remarks> public Type GetType (string typeName, bool throwIfNotFound) { EnsureAssembliesLoaded (); @@ -237,11 +369,49 @@ namespace Mono.Addins } } + /// <summary> + /// Creates an instance of a type defined in the add-in + /// </summary> + /// <param name="typeName"> + /// Name of the type. + /// </param> + /// <returns> + /// A new instance of the type + /// </returns> + /// <remarks> + /// The type will be looked up in the assemblies that implement the add-in, + /// and recursivelly in all add-ins on which it depends. + /// + /// This method throws an InvalidOperationException if the type can't be found. + /// + /// The specified type must have a default constructor. + /// </remarks> public object CreateInstance (string typeName) { return CreateInstance (typeName, true); } + /// <summary> + /// Creates an instance of a type defined in the add-in + /// </summary> + /// <param name="typeName"> + /// Name of the type. + /// </param> + /// <param name="throwIfNotFound"> + /// Indicates whether the method should throw an exception if the type can't be found. + /// </param> + /// <returns> + /// A new instance of the type + /// </returns> + /// <remarks> + /// The type will be looked up in the assemblies that implement the add-in, + /// and recursivelly in all add-ins on which it depends. + /// + /// If the type can't be found, this method throw a InvalidOperationException if + /// 'throwIfNotFound' is 'true', or 'null' otherwise. + /// + /// The specified type must have a default constructor. + /// </remarks> public object CreateInstance (string typeName, bool throwIfNotFound) { Type type = GetType (typeName, throwIfNotFound); @@ -251,16 +421,43 @@ namespace Mono.Addins return Activator.CreateInstance (type, true); } + /// <summary> + /// Gets the path of an add-in file + /// </summary> + /// <param name="fileName"> + /// Relative path of the file + /// </param> + /// <returns> + /// Full path of the file + /// </returns> + /// <remarks> + /// This method can be used to get the full path of a data file deployed together with the add-in. + /// </remarks> public string GetFilePath (string fileName) { return Path.Combine (baseDirectory, fileName); } - + + /// <summary> + /// Gets the path of an add-in file + /// </summary> + /// <param name="filePath"> + /// Components of the file path + /// </param> + /// <returns> + /// Full path of the file + /// </returns> + /// <remarks> + /// This method can be used to get the full path of a data file deployed together with the add-in. + /// </remarks> public string GetFilePath (params string[] filePath) { return Path.Combine (baseDirectory, string.Join ("" + Path.DirectorySeparatorChar, filePath)); } + /// <summary> + /// Path to a directory where add-ins can store private configuration or status data + /// </summary> public string PrivateDataPath { get { if (privatePath == null) { @@ -272,11 +469,38 @@ namespace Mono.Addins } } + /// <summary> + /// Gets the content of a resource + /// </summary> + /// <param name="resourceName"> + /// Name of the resource + /// </param> + /// <returns> + /// Content of the resource, or null if not found + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public Stream GetResource (string resourceName) { return GetResource (resourceName, false); } + /// <summary> + /// Gets the content of a resource + /// </summary> + /// <param name="resourceName"> + /// Name of the resource + /// </param> + /// <param name="throwIfNotFound"> + /// When set to true, an exception will be thrown if the resource is not found. + /// </param> + /// <returns> + /// Content of the resource. + /// </returns> + /// <remarks> + /// The add-in engine will look for resources in the main add-in assembly and in all included add-in assemblies. + /// </remarks> public Stream GetResource (string resourceName, bool throwIfNotFound) { EnsureAssembliesLoaded (); @@ -302,6 +526,9 @@ namespace Mono.Addins return null; } + /// <summary> + /// Localizer which can be used to localize strings defined in this add-in + /// </summary> public AddinLocalizer Localizer { get { if (localizer != null) diff --git a/Mono.Addins/Mono.Addins/TypeExtensionNode.cs b/Mono.Addins/Mono.Addins/TypeExtensionNode.cs index 9e7a7a3..4f8bc3d 100644 --- a/Mono.Addins/Mono.Addins/TypeExtensionNode.cs +++ b/Mono.Addins/Mono.Addins/TypeExtensionNode.cs @@ -32,6 +32,28 @@ using System.Xml; namespace Mono.Addins { + /// <summary> + /// An extension node which specifies a type. + /// </summary> + /// <remarks> + /// This class is a kind of Mono.Addins.ExtensionNode which can be used to register + /// types in an extension point. This is a very common case: a host application + /// defines an interface, and add-ins create classes that implement that interface. + /// The host will define an extension point which will use TypeExtensionNode as node + /// type. Add-ins will register the classes they implement in that extension point. + /// + /// When the nodes of an extension point are of type TypeExtensionNode it is then + /// possible to use query methods such as AddinManager.GetExtensionObjects(string), + /// which will get all nodes in the provided extension path and will create an object + /// for each node. + /// + /// When declaring extension nodes in an add-in manifest, the class names can be + /// specified using the 'class' or 'type' attribute. If none of those attributes is + /// provided, the class name will be taken from the 'id' attribute. + /// + /// TypeExtensionNode is the default extension type used when no type is provided + /// in the definition of an extension point. + /// </remarks> [ExtensionNode ("Type", Description="Specifies a class that will be used to create an extension object.")] [NodeAttribute ("class", typeof(Type), false, Description="Name of the class. If a value is not provided, the class name will be taken from the 'id' attribute")] public class TypeExtensionNode: InstanceExtensionNode @@ -53,7 +75,10 @@ namespace Mono.Addins { return Activator.CreateInstance (Type); } - + + /// <summary> + /// Type of the object that this node creates + /// </summary> public Type Type { get { if (type == null) { @@ -66,10 +91,19 @@ namespace Mono.Addins } } + /// <summary> + /// An extension node which specifies a type with custom extension metadata + /// </summary> + /// <remarks> + /// This is the default type for type extension nodes bound to a custom extension attribute. + /// </remarks> public class TypeExtensionNode<T>: TypeExtensionNode where T:CustomExtensionAttribute { T data; + /// <summary> + /// The custom attribute containing the extension metadata + /// </summary> [NodeAttribute] public T Data { get { return data; } diff --git a/Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs b/Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs index d73640b..3bb89f3 100644 --- a/Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs +++ b/Mono.Addins/Mono.Addins/TypeExtensionPointAttribute.cs @@ -31,6 +31,9 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares an extension point bound to a type + /// </summary> [AttributeUsage (AttributeTargets.Class | AttributeTargets.Interface, AllowMultiple=true)] public class TypeExtensionPointAttribute: Attribute { @@ -43,35 +46,59 @@ namespace Mono.Addins Type customAttributeType; string customAttributeTypeName; + /// <summary> + /// Initializes a new instance + /// </summary> public TypeExtensionPointAttribute () { } + /// <summary> + /// Initializes a new instance + /// </summary> + /// <param name="path"> + /// Path that identifies the extension point + /// </param> public TypeExtensionPointAttribute (string path) { this.path = path; } + /// <summary> + /// Path that identifies the extension point + /// </summary> public string Path { get { return path != null ? path : string.Empty; } set { path = value; } } + /// <summary> + /// Description of the extension point. + /// </summary> public string Description { get { return desc != null ? desc : string.Empty; } set { desc = value; } } + /// <summary> + /// Element name to be used when defining an extension in an XML manifest. The default name is "Type". + /// </summary> public string NodeName { get { return nodeName != null && nodeName.Length > 0 ? nodeName : "Type"; } set { nodeName = value; } } + /// <summary> + /// Display name of the extension point. + /// </summary> public string Name { get { return name != null ? name : string.Empty; } set { name = value; } } + /// <summary> + /// Type of the extension node to be created for extensions + /// </summary> public Type NodeType { get { return nodeType != null ? nodeType : typeof(TypeExtensionNode); } set { nodeType = value; nodeTypeName = value.FullName; } @@ -82,6 +109,9 @@ namespace Mono.Addins set { nodeTypeName = value; nodeType = null; } } + /// <summary> + /// Type of the custom attribute to be used to specify metadata for the extension point + /// </summary> public Type ExtensionAttributeType { get { return this.customAttributeType; } set { this.customAttributeType = value; customAttributeTypeName = value.FullName; } |