diff options
author | Lluis Sanchez <lluis@novell.com> | 2010-05-27 16:21:02 +0400 |
---|---|---|
committer | Lluis Sanchez <lluis@novell.com> | 2010-05-27 16:21:02 +0400 |
commit | 50bc9e60c8bef251892b8d97c133f2a70ebae74f (patch) | |
tree | 3d705d8b2b1dfedbfca246304b2893e338ae046f | |
parent | 11fe1fb5eff294e766d38fb1b48356f3eba015af (diff) |
* Mono.Addins/AddinEngine.cs:
* Mono.Addins/AddinManager.cs:
* Mono.Addins/AddinRegistry.cs:
* Mono.Addins/AddinEventArgs.cs:
* Mono.Addins/AddinLocalizer.cs:
* Mono.Addins/AddinAttribute.cs:
* Mono.Addins/AddinErrorEventArgs.cs:
* Mono.Addins/AddinModuleAttribute.cs:
* Mono.Addins/AddinAuthorAttribute.cs:
* Mono.Addins/AddinDependencyAttribute.cs:
* Mono.Addins/AddinLocalizerGettextAttribute.cs: Added some API
documentation.
svn path=/trunk/mono-addins/; revision=158026
-rw-r--r-- | Mono.Addins/ChangeLog | 15 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinAttribute.cs | 46 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinAuthorAttribute.cs | 12 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinDependencyAttribute.cs | 18 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinEngine.cs | 109 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinErrorEventArgs.cs | 9 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinEventArgs.cs | 6 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinLocalizer.cs | 91 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinLocalizerGettextAttribute.cs | 20 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinManager.cs | 469 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinModuleAttribute.cs | 12 | ||||
-rw-r--r-- | Mono.Addins/Mono.Addins/AddinRegistry.cs | 225 |
12 files changed, 1012 insertions, 20 deletions
diff --git a/Mono.Addins/ChangeLog b/Mono.Addins/ChangeLog index 559a191..2a6c532 100644 --- a/Mono.Addins/ChangeLog +++ b/Mono.Addins/ChangeLog @@ -1,3 +1,18 @@ +2010-05-27 Lluis Sanchez Gual <lluis@novell.com> + + * Mono.Addins/AddinEngine.cs: + * Mono.Addins/AddinManager.cs: + * Mono.Addins/AddinRegistry.cs: + * Mono.Addins/AddinEventArgs.cs: + * Mono.Addins/AddinLocalizer.cs: + * Mono.Addins/AddinAttribute.cs: + * Mono.Addins/AddinErrorEventArgs.cs: + * Mono.Addins/AddinModuleAttribute.cs: + * Mono.Addins/AddinAuthorAttribute.cs: + * Mono.Addins/AddinDependencyAttribute.cs: + * Mono.Addins/AddinLocalizerGettextAttribute.cs: Added some + API documentation. + 2010-05-25 Lluis Sanchez Gual <lluis@novell.com> * Mono.Addins.Database/AddinScanResult.cs: Properly resolve diff --git a/Mono.Addins/Mono.Addins/AddinAttribute.cs b/Mono.Addins/Mono.Addins/AddinAttribute.cs index 72dcf8a..6f9f738 100644 --- a/Mono.Addins/Mono.Addins/AddinAttribute.cs +++ b/Mono.Addins/Mono.Addins/AddinAttribute.cs @@ -32,6 +32,9 @@ using Mono.Addins.Description; namespace Mono.Addins { + /// <summary> + /// Marks an assembly as being an add-in. + /// </summary> [AttributeUsage (AttributeTargets.Assembly)] public class AddinAttribute: Attribute { @@ -44,56 +47,99 @@ namespace Mono.Addins string compatVersion; string url; + /// <summary> + /// Initializes an add-in marker attribute + /// </summary> public AddinAttribute () { } + /// <summary> + /// Initializes an add-in marker attribute + /// </summary> + /// <param name="id"> + /// Identifier of the add-in + /// </param> public AddinAttribute (string id) { this.id = id; } + /// <summary> + /// Initializes an add-in marker attribute + /// </summary> + /// <param name="id"> + /// Identifier of the add-in + /// </param> + /// <param name="version"> + /// Version of the add-in + /// </param> public AddinAttribute (string id, string version) { this.id = id; this.version = version; } + /// <summary> + /// Identifier of the add-in. + /// </summary> public string Id { get { return id != null ? id : string.Empty; } set { id = value; } } + /// <summary> + /// Version of the add-in. + /// </summary> public string Version { get { return version != null ? version : string.Empty; } set { version = value; } } + /// <summary> + /// Version of the add-in with which this add-in is backwards compatible. + /// </summary> public string CompatVersion { get { return compatVersion != null ? compatVersion : string.Empty; } set { compatVersion = value; } } + /// <summary> + /// Namespace of the add-in + /// </summary> public string Namespace { get { return ns != null ? ns : string.Empty; } set { ns = value; } } + /// <summary> + /// Category of the add-in + /// </summary> public string Category { get { return category != null ? category : string.Empty; } set { category = value; } } + /// <summary> + /// Url to a web page with more information about the add-in + /// </summary> public string Url { get { return url != null ? url : string.Empty; } set { url = value; } } + /// <summary> + /// When set to True, the add-in will be automatically enabled after installing. + /// It's True by default. + /// </summary> public bool EnabledByDefault { get { return this.enabledByDefault; } set { this.enabledByDefault = value; } } + /// <summary> + /// Add-in flags + /// </summary> public AddinFlags Flags { get { return this.flags; } set { this.flags = value; } diff --git a/Mono.Addins/Mono.Addins/AddinAuthorAttribute.cs b/Mono.Addins/Mono.Addins/AddinAuthorAttribute.cs index 000117d..1ef0321 100644 --- a/Mono.Addins/Mono.Addins/AddinAuthorAttribute.cs +++ b/Mono.Addins/Mono.Addins/AddinAuthorAttribute.cs @@ -28,16 +28,28 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares an author of the add-in + /// </summary> [AttributeUsage (AttributeTargets.Assembly, AllowMultiple=true)] public class AddinAuthorAttribute: Attribute { string name; + /// <summary> + /// Initializes the attribute + /// </summary> + /// <param name="name"> + /// Name of the author + /// </param> public AddinAuthorAttribute (string name) { this.name = name; } + /// <summary> + /// Author name + /// </summary> public string Name { get { return this.name; } set { this.name = value; } diff --git a/Mono.Addins/Mono.Addins/AddinDependencyAttribute.cs b/Mono.Addins/Mono.Addins/AddinDependencyAttribute.cs index 703053d..3009a7d 100644 --- a/Mono.Addins/Mono.Addins/AddinDependencyAttribute.cs +++ b/Mono.Addins/Mono.Addins/AddinDependencyAttribute.cs @@ -31,22 +31,40 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares a dependency on an add-in or add-in host + /// </summary> [AttributeUsage (AttributeTargets.Assembly, AllowMultiple=true)] public class AddinDependencyAttribute: Attribute { string id; string version; + /// <summary> + /// Initializes the attribute + /// </summary> + /// <param name="id"> + /// Identifier of the add-in + /// </param> + /// <param name="version"> + /// Version of the add-in + /// </param> public AddinDependencyAttribute (string id, string version) { this.id = id; this.version = version; } + /// <summary> + /// Identifier of the add-in + /// </summary> public string Id { get { return id; } } + /// <summary> + /// Version of the add-in + /// </summary> public string Version { get { return version; } } diff --git a/Mono.Addins/Mono.Addins/AddinEngine.cs b/Mono.Addins/Mono.Addins/AddinEngine.cs index 2131085..08422f2 100644 --- a/Mono.Addins/Mono.Addins/AddinEngine.cs +++ b/Mono.Addins/Mono.Addins/AddinEngine.cs @@ -38,6 +38,17 @@ using Mono.Addins.Localization; namespace Mono.Addins { + /// <summary> + /// An add-in engine. + /// </summary> + /// <remarks> + /// This class allows hosting several independent add-in engines in a single application domain. + /// In general, applications use the AddinManager class to query and manage extensions. This class is static, + /// so the API is easily accessible. However, some kind applications may need to use several isolated + /// add-in engines, and in this case the AddinManager class can't be used, because it is bound to a single + /// add-in engine. Those applications can instead create several instances of the AddinEngine class. Each + /// add-in engine can be independently initialized with different add-in registries and extension models. + /// </remarks> public class AddinEngine: ExtensionContext { bool initialized; @@ -61,6 +72,16 @@ namespace Mono.Addins { } + /// <summary> + /// Initializes the add-in engine + /// </summary> + /// <param name="configDir"> + /// Location of the add-in registry. + /// </param> + /// <remarks>The add-in engine needs to be initialized before doing any add-in operation. + /// When initialized with this method, it will look for add-in in the add-in registry + /// located in the specified path. + /// </remarks> public void Initialize (string configDir) { if (initialized) @@ -100,6 +121,9 @@ namespace Mono.Addins AppDomain.CurrentDomain.AssemblyLoad += new AssemblyLoadEventHandler (OnAssemblyLoaded); } + /// <summary> + /// Finalizes the add-in engine. + /// </summary> public void Shutdown () { initialized = false; @@ -112,6 +136,12 @@ namespace Mono.Addins Clear (); } + /// <summary> + /// Sets the default localizer to be used for this add-in engine + /// </summary> + /// <param name="localizer"> + /// The add-in localizer + /// </param> public void InitializeDefaultLocalizer (IAddinLocalizer localizer) { CheckInitialized (); @@ -125,15 +155,28 @@ namespace Mono.Addins get { return startupDirectory; } } + /// <summary> + /// Gets whether the add-in engine has been initialized. + /// </summary> public bool IsInitialized { get { return initialized; } } + /// <summary> + /// Gets the default add-in installer + /// </summary> + /// <remarks> + /// The default installer is used by the CheckInstalled method to request + /// the installation of missing add-ins. + /// </remarks> public IAddinInstaller DefaultInstaller { get { return installer; } set { installer = value; } } + /// <summary> + /// Gets the default localizer for this add-in engine + /// </summary> public AddinLocalizer DefaultLocalizer { get { CheckInitialized (); @@ -148,6 +191,9 @@ namespace Mono.Addins get { return this; } } + /// <summary> + /// Gets the localizer for the add-in that is invoking this property + /// </summary> public AddinLocalizer CurrentLocalizer { get { CheckInitialized (); @@ -160,6 +206,9 @@ namespace Mono.Addins } } + /// <summary> + /// Gets a reference to the RuntimeAddin object for the add-in that is invoking this property + /// </summary> public RuntimeAddin CurrentAddin { get { CheckInitialized (); @@ -168,6 +217,9 @@ namespace Mono.Addins } } + /// <summary> + /// Gets the add-in registry bound to this add-in engine + /// </summary> public AddinRegistry Registry { get { CheckInitialized (); @@ -180,11 +232,23 @@ namespace Mono.Addins return (RuntimeAddin) loadedAssemblies [asm]; } - // This method checks if the specified add-ins are installed. - // If some of the add-ins are not installed, it will use - // the installer assigned to the DefaultAddinInstaller property - // to install them. If the installation fails, or if DefaultAddinInstaller - // is not set, an exception will be thrown. + /// <summary> + /// Checks if the provided add-ins are installed, and requests the installation of those + /// which aren't. + /// </summary> + /// <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 checked. + /// </param> + /// <remarks> + /// This method checks if the specified add-ins are installed. + /// If some of the add-ins are not installed, it will use + /// the installer assigned to the DefaultAddinInstaller property + /// to install them. If the installation fails, or if DefaultAddinInstaller + /// is not set, an exception will be thrown. + /// </remarks> public void CheckInstalled (string message, params string[] addinIds) { ArrayList notInstalled = new ArrayList (); @@ -214,7 +278,16 @@ namespace Mono.Addins get { return checkAssemblyLoadConflicts; } set { checkAssemblyLoadConflicts = value; } } - + + /// <summary> + /// Checks if an add-in has been loaded. + /// </summary> + /// <param name="id"> + /// Full identifier of the add-in. + /// </param> + /// <returns> + /// True if the add-in is loaded. + /// </returns> public bool IsAddinLoaded (string id) { CheckInitialized (); @@ -247,6 +320,21 @@ namespace Mono.Addins } } + /// <summary> + /// Forces the loading of an add-in. + /// </summary> + /// <param name="statusMonitor"> + /// Status monitor to keep track of the loading process. + /// </param> + /// <param name="id"> + /// Full identifier of the add-in to load. + /// </param> + /// <remarks> + /// This method loads all assemblies that belong to an add-in in memory. + /// All add-ins on which the specified add-in depends will also be loaded. + /// Notice that in general add-ins don't need to be explicitely loaded using + /// this method, since the add-in engine will load them on demand. + /// </remarks> public void LoadAddin (IProgressStatus statusMonitor, string id) { CheckInitialized (); @@ -516,6 +604,15 @@ namespace Mono.Addins } } + /// <summary> + /// Creates a new extension context. + /// </summary> + /// <returns> + /// The new extension context. + /// </returns> + /// <remarks> + /// Extension contexts can be used to query the extension model using particular condition values. + /// </remarks> public ExtensionContext CreateExtensionContext () { CheckInitialized (); diff --git a/Mono.Addins/Mono.Addins/AddinErrorEventArgs.cs b/Mono.Addins/Mono.Addins/AddinErrorEventArgs.cs index 697f531..6d12493 100644 --- a/Mono.Addins/Mono.Addins/AddinErrorEventArgs.cs +++ b/Mono.Addins/Mono.Addins/AddinErrorEventArgs.cs @@ -33,6 +33,9 @@ namespace Mono.Addins { public delegate void AddinErrorEventHandler (object sender, AddinErrorEventArgs args); + /// <summary> + /// Provides information about an add-in loading error. + /// </summary> public class AddinErrorEventArgs: AddinEventArgs { Exception exception; @@ -44,10 +47,16 @@ namespace Mono.Addins this.exception = exception; } + /// <summary> + /// Exception that caused the error. + /// </summary> public Exception Exception { get { return exception; } } + /// <summary> + /// Error message + /// </summary> public string Message { get { return message; } } diff --git a/Mono.Addins/Mono.Addins/AddinEventArgs.cs b/Mono.Addins/Mono.Addins/AddinEventArgs.cs index dc5aefb..c419705 100644 --- a/Mono.Addins/Mono.Addins/AddinEventArgs.cs +++ b/Mono.Addins/Mono.Addins/AddinEventArgs.cs @@ -33,6 +33,9 @@ namespace Mono.Addins { public delegate void AddinEventHandler (object sender, AddinEventArgs args); + /// <summary> + /// Provides information about an add-in engine event. + /// </summary> public class AddinEventArgs: EventArgs { string addinId; @@ -42,6 +45,9 @@ namespace Mono.Addins this.addinId = addinId; } + /// <summary> + /// Identifier of the add-in that generated the event. + /// </summary> public string AddinId { get { return addinId; } } diff --git a/Mono.Addins/Mono.Addins/AddinLocalizer.cs b/Mono.Addins/Mono.Addins/AddinLocalizer.cs index 2c77c95..332c2df 100644 --- a/Mono.Addins/Mono.Addins/AddinLocalizer.cs +++ b/Mono.Addins/Mono.Addins/AddinLocalizer.cs @@ -31,6 +31,9 @@ using Mono.Addins.Localization; namespace Mono.Addins { + /// <summary> + /// Converts message identifiers to localized messages. + /// </summary> public class AddinLocalizer { IAddinLocalizer localizer; @@ -41,22 +44,70 @@ namespace Mono.Addins this.localizer = localizer; pluralLocalizer = localizer as IPluralAddinLocalizer; } - + + /// <summary> + /// Gets a localized message + /// </summary> + /// <param name="msgid"> + /// Message identifier + /// </param> + /// <returns> + /// The localized message + /// </returns> public string GetString (string msgid) { return localizer.GetString (msgid); } + /// <summary> + /// Gets a formatted and localized message + /// </summary> + /// <param name="msgid"> + /// Message identifier (can contain string format placeholders) + /// </param> + /// <param name="args"> + /// Arguments for the string format operation + /// </param> + /// <returns> + /// The formatted and localized string + /// </returns> public string GetString (string msgid, params string[] args) { return string.Format (localizer.GetString (msgid), args); } + /// <summary> + /// Gets a formatted and localized message + /// </summary> + /// <param name="msgid"> + /// Message identifier (can contain string format placeholders) + /// </param> + /// <param name="args"> + /// Arguments for the string format operation + /// </param> + /// <returns> + /// The formatted and localized string + /// </returns> public string GetString (string msgid, params object[] args) { return string.Format (localizer.GetString (msgid), args); } - + + /// <summary> + /// Gets a localized plural form for a message identifier + /// </summary> + /// <param name="msgid"> + /// Message identifier for the singular form + /// </param> + /// <param name="defaultPlural"> + /// Default result message for the plural form + /// </param> + /// <param name="n"> + /// Value count. Determines wether to use singular or plural form. + /// </param> + /// <returns> + /// The localized message + /// </returns> public string GetPluralString (string msgid, string defaultPlural, int n) { // If the localizer does not support plural forms, just use GetString to @@ -69,11 +120,47 @@ namespace Mono.Addins return GetString (msgid); } + /// <summary> + /// Gets a localized and formatted plural form for a message identifier + /// </summary> + /// <param name="msgid"> + /// Message identifier for the singular form (can contain string format placeholders) + /// </param> + /// <param name="defaultPlural"> + /// Default result message for the plural form (can contain string format placeholders) + /// </param> + /// <param name="n"> + /// Value count. Determines whether to use singular or plural form. + /// </param> + /// <param name="args"> + /// Arguments for the string format operation + /// </param> + /// <returns> + /// The localized message + /// </returns> public string GetPluralString (string singular, string defaultPlural, int n, params string[] args) { return string.Format (GetPluralString (singular, defaultPlural, n), args); } + /// <summary> + /// Gets a localized and formatted plural form for a message identifier + /// </summary> + /// <param name="msgid"> + /// Message identifier for the singular form (can contain string format placeholders) + /// </param> + /// <param name="defaultPlural"> + /// Default result message for the plural form (can contain string format placeholders) + /// </param> + /// <param name="n"> + /// Value count. Determines whether to use singular or plural form. + /// </param> + /// <param name="args"> + /// Arguments for the string format operation + /// </param> + /// <returns> + /// The localized message + /// </returns> public string GetPluralString (string singular, string defaultPlural, int n, params object[] args) { return string.Format (GetPluralString (singular, defaultPlural, n), args); diff --git a/Mono.Addins/Mono.Addins/AddinLocalizerGettextAttribute.cs b/Mono.Addins/Mono.Addins/AddinLocalizerGettextAttribute.cs index fcc1bc5..529373d 100644 --- a/Mono.Addins/Mono.Addins/AddinLocalizerGettextAttribute.cs +++ b/Mono.Addins/Mono.Addins/AddinLocalizerGettextAttribute.cs @@ -28,6 +28,9 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares a Gettext-based localizer for an add-in + /// </summary> [AttributeUsage (AttributeTargets.Assembly)] public class AddinLocalizerGettextAttribute: Attribute { @@ -49,16 +52,31 @@ namespace Mono.Addins this.location = location; } + /// <summary> + /// Name of the catalog which contains the strings. + /// </summary> public string Catalog { get { return this.catalog; } set { this.catalog = value; } } + /// <summary> + /// Relative path to the location of the catalog. This path must be relative to the add-in location. + /// </summary> + /// <remarks> + /// When not specified, the default value of this property is 'locale'. + /// The location path must contain a directory structure like this: + /// + /// {language-id}/LC_MESSAGES/{Catalog}.mo + /// + /// For example, the catalog for spanish strings would be located at: + /// + /// locale/es/LC_MESSAGES/some-addin.mo + /// </remarks> public string Location { get { return this.location; } set { this.location = value; } } - } } diff --git a/Mono.Addins/Mono.Addins/AddinManager.cs b/Mono.Addins/Mono.Addins/AddinManager.cs index dfed58c..8745085 100644 --- a/Mono.Addins/Mono.Addins/AddinManager.cs +++ b/Mono.Addins/Mono.Addins/AddinManager.cs @@ -36,6 +36,9 @@ using Mono.Addins.Localization; namespace Mono.Addins { + /// <summary> + /// Provides access to add-in and extension model management operations. + /// </summary> public class AddinManager { static AddinEngine sessionService; @@ -44,6 +47,13 @@ namespace Mono.Addins { } + /// <summary> + /// Initializes the add-in engine. + /// </summary> + /// <remarks> + /// The add-in engine needs to be initialized before doing any add-in operation. + /// When initialized with this method, it will look for add-in in the global add-in registry. + /// </remarks> public static void Initialize () { // Code not shared with the other Initialize since I need to get the calling assembly @@ -52,6 +62,17 @@ namespace Mono.Addins AddinEngine.Initialize (null, asm); } + /// <summary> + /// Initializes the add-in engine. + /// </summary> + /// <param name="configDir"> + /// Location of the add-in registry. + /// </param> + /// <remarks> + /// The add-in engine needs to be initialized before doing any add-in operation. + /// When initialized with this method, it will look for add-in in the add-in + /// registry located in the specified path. + /// </remarks> public static void Initialize (string configDir) { Assembly asm = Assembly.GetEntryAssembly (); @@ -59,11 +80,20 @@ namespace Mono.Addins AddinEngine.Initialize (configDir, asm); } + /// <summary> + /// Finalizes an add-in engine. + /// </summary> public static void Shutdown () { AddinEngine.Shutdown (); } + /// <summary> + /// Sets the default localizer to be used for this add-in engine + /// </summary> + /// <param name="localizer"> + /// The add-in localizer + /// </param> public static void InitializeDefaultLocalizer (IAddinLocalizer localizer) { AddinEngine.InitializeDefaultLocalizer (localizer); @@ -73,21 +103,37 @@ namespace Mono.Addins get { return AddinEngine.StartupDirectory; } } + /// <summary> + /// Gets whether the add-in engine has been initialized. + /// </summary> public static bool IsInitialized { get { return AddinEngine.IsInitialized; } } + /// <summary> + /// Gets the default add-in installer + /// </summary> + /// <remarks> + /// The default installer is used by the CheckInstalled method to request + /// the installation of missing add-ins. + /// </remarks> public static IAddinInstaller DefaultInstaller { get { return AddinEngine.DefaultInstaller; } set { AddinEngine.DefaultInstaller = value; } } + /// <summary> + /// Gets the default localizer for this add-in engine + /// </summary> public static AddinLocalizer DefaultLocalizer { get { return AddinEngine.DefaultLocalizer; } } + /// <summary> + /// Gets the localizer for the add-in that is invoking this property + /// </summary> public static AddinLocalizer CurrentLocalizer { get { AddinEngine.CheckInitialized (); @@ -99,6 +145,9 @@ namespace Mono.Addins } } + /// <summary> + /// Gets a reference to the RuntimeAddin object for the add-in that is invoking this property + /// </summary> public static RuntimeAddin CurrentAddin { get { AddinEngine.CheckInitialized (); @@ -106,6 +155,9 @@ namespace Mono.Addins } } + /// <summary> + /// Gets the default add-in engine + /// </summary> public static AddinEngine AddinEngine { get { if (sessionService == null) @@ -115,184 +167,581 @@ namespace Mono.Addins } } + /// <summary> + /// Gets the add-in registry bound to the default add-in engine + /// </summary> public static AddinRegistry Registry { get { return AddinEngine.Registry; } } - // This method checks if the specified add-ins are installed. - // If some of the add-ins are not installed, it will use - // the installer assigned to the DefaultAddinInstaller property - // to install them. If the installation fails, or if DefaultAddinInstaller - // is not set, an exception will be thrown. + /// <summary> + /// Checks if the provided add-ins are installed, and requests the installation of those + /// which aren't. + /// </summary> + /// <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 checked. + /// </param> + /// <remarks> + /// This method checks if the specified add-ins are installed. + /// If some of the add-ins are not installed, it will use + /// the installer assigned to the DefaultAddinInstaller property + /// to install them. If the installation fails, or if DefaultAddinInstaller + /// is not set, an exception will be thrown. + /// </remarks> public static void CheckInstalled (string message, params string[] addinIds) { AddinEngine.CheckInstalled (message, addinIds); } + /// <summary> + /// Checks if an add-in has been loaded. + /// </summary> + /// <param name="id"> + /// Full identifier of the add-in. + /// </param> + /// <returns> + /// True if the add-in is loaded. + /// </returns> public static bool IsAddinLoaded (string id) { return AddinEngine.IsAddinLoaded (id); } + /// <summary> + /// Forces the loading of an add-in. + /// </summary> + /// <param name="statusMonitor"> + /// Status monitor to keep track of the loading process. + /// </param> + /// <param name="id"> + /// Full identifier of the add-in to load. + /// </param> + /// <remarks> + /// This method loads all assemblies that belong to an add-in in memory. + /// All add-ins on which the specified add-in depends will also be loaded. + /// Notice that in general add-ins don't need to be explicitely loaded using + /// this method, since the add-in engine will load them on demand. + /// </remarks> public static void LoadAddin (IProgressStatus statusMonitor, string id) { AddinEngine.LoadAddin (statusMonitor, id); } + /// <summary> + /// Creates a new extension context. + /// </summary> + /// <returns> + /// The new extension context. + /// </returns> + /// <remarks> + /// Extension contexts can be used to query the extension model using particular condition values. + /// </remarks> public static ExtensionContext CreateExtensionContext () { return AddinEngine.CreateExtensionContext (); } + /// <summary> + /// Returns the extension node in a path + /// </summary> + /// <param name="path"> + /// Location of the node. + /// </param> + /// <returns> + /// The node, or null if not found. + /// </returns> public static ExtensionNode GetExtensionNode (string path) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNode (path); } - public static ExtensionNode GetExtensionNode<T> (string path) where T:ExtensionNode + /// <summary> + /// Returns the extension node in a path + /// </summary> + /// <param name="path"> + /// Location of the node. + /// </param> + /// <returns> + /// The node, or null if not found. + /// </returns> + public static T GetExtensionNode<T> (string path) where T:ExtensionNode { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNode<T> (path); } + /// <summary> + /// Gets extension nodes registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path.> + /// </param> + /// <returns> + /// All nodes registered in the provided path. + /// </returns> public static ExtensionNodeList GetExtensionNodes (string path) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes (path); } + /// <summary> + /// Gets extension nodes registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <param name="type"> + /// Expected node type. + /// </param> + /// <returns> + /// A list of nodes + /// </returns> + /// <remarks> + /// This method returns all nodes registered under the provided path. + /// It will throw a InvalidOperationException if the type of one of + /// the registered nodes is not assignable to the provided type. + /// </remarks> public static ExtensionNodeList GetExtensionNodes (string path, Type type) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes (path, type); } + /// <summary> + /// Gets extension nodes registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <returns> + /// A list of nodes + /// </returns> + /// <remarks> + /// This method returns all nodes registered under the provided path. + /// It will throw a InvalidOperationException if the type of one of + /// the registered nodes is not assignable to the provided type. + /// </remarks> public static ExtensionNodeList<T> GetExtensionNodes<T> (string path) where T:ExtensionNode { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes<T> (path); } - + + /// <summary> + /// Gets extension nodes for a type extension point + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <returns> + /// A list of nodes + /// </returns> + /// <remarks> + /// This method returns all extension nodes bound to the provided type. + /// </remarks> public static ExtensionNodeList GetExtensionNodes (Type instanceType) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes (instanceType); } - + + /// <summary> + /// Gets extension nodes for a type extension point + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <param name="expectedNodeType"> + /// Expected extension node type + /// </param> + /// <returns> + /// A list of nodes + /// </returns> + /// <remarks> + /// This method returns all nodes registered for the provided type. + /// It will throw a InvalidOperationException if the type of one of + /// the registered nodes is not assignable to the provided node type. + /// </remarks> public static ExtensionNodeList GetExtensionNodes (Type instanceType, Type expectedNodeType) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes (instanceType, expectedNodeType); } + /// <summary> + /// Gets extension nodes for a type extension point + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <returns> + /// A list of nodes + /// </returns> + /// <remarks> + /// This method returns all nodes registered for the provided type. + /// It will throw a InvalidOperationException if the type of one of + /// the registered nodes is not assignable to the specified node type argument. + /// </remarks> public static ExtensionNodeList<T> GetExtensionNodes<T> (Type instanceType) where T: ExtensionNode { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionNodes<T> (instanceType); } + /// <summary> + /// Gets extension objects registered for a type extension point. + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <returns> + /// A list of objects + /// </returns> public static object[] GetExtensionObjects (Type instanceType) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (instanceType); } + /// <summary> + /// Gets extension objects registered for a type extension point. + /// </summary> + /// <returns> + /// A list of objects + /// </returns> + /// <remarks> + /// The type argument of this generic method is the type that defines + /// the extension point. + /// </remarks> public static T[] GetExtensionObjects<T> () { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects<T> (); } - + + /// <summary> + /// Gets extension objects registered for a type extension point. + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <param name="reuseCachedInstance"> + /// When set to True, it will return instances created in previous calls. + /// </param> + /// <returns> + /// A list of extension objects. + /// </returns> public static object[] GetExtensionObjects (Type instanceType, bool reuseCachedInstance) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (instanceType, reuseCachedInstance); } + /// <summary> + /// Gets extension objects registered for a type extension point. + /// </summary> + /// <param name="reuseCachedInstance"> + /// When set to True, it will return instances created in previous calls. + /// </param> + /// <returns> + /// A list of extension objects. + /// </returns> + /// <remarks> + /// The type argument of this generic method is the type that defines + /// the extension point. + /// </remarks> public static T[] GetExtensionObjects<T> (bool reuseCachedInstance) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects<T> (reuseCachedInstance); } + /// <summary> + /// Gets extension objects registered in a path + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node. + /// </remarks> public static object[] GetExtensionObjects (string path) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (path); } + /// <summary> + /// Gets extension objects registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <param name="reuseCachedInstance"> + /// When set to True, it will return instances created in previous calls. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node (or TypeExtensionNode.GetInstance() if + /// reuseCachedInstance is set to true) + /// </remarks> public static object[] GetExtensionObjects (string path, bool reuseCachedInstance) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (path, reuseCachedInstance); } + /// <summary> + /// Gets extension objects registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <param name="arrayElementType"> + /// Type of the return array elements. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node. + /// + /// An InvalidOperationException exception is thrown if one of the found + /// objects is not a subclass of the provided type. + /// </remarks> public static object[] GetExtensionObjects (string path, Type arrayElementType) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (path, arrayElementType); } + /// <summary> + /// Gets extension objects registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node. + /// + /// An InvalidOperationException exception is thrown if one of the found + /// objects is not a subclass of the provided type. + /// </remarks> public static T[] GetExtensionObjects<T> (string path) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects<T> (path); } + /// <summary> + /// Gets extension objects registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <param name="arrayElementType"> + /// Type of the return array elements. + /// </param> + /// <param name="reuseCachedInstance"> + /// When set to True, it will return instances created in previous calls. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node (or TypeExtensionNode.GetInstance() if + /// reuseCachedInstance is set to true). + /// + /// An InvalidOperationException exception is thrown if one of the found + /// objects is not a subclass of the provided type. + /// </remarks> public static object[] GetExtensionObjects (string path, Type arrayElementType, bool reuseCachedInstance) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects (path, arrayElementType, reuseCachedInstance); } + /// <summary> + /// Gets extension objects registered in a path. + /// </summary> + /// <param name="path"> + /// An extension path. + /// </param> + /// <param name="reuseCachedInstance"> + /// When set to True, it will return instances created in previous calls. + /// </param> + /// <returns> + /// An array of objects registered in the path. + /// </returns> + /// <remarks> + /// This method can only be used if all nodes in the provided extension path + /// are of type Mono.Addins.TypeExtensionNode. The returned array is composed + /// by all objects created by calling the TypeExtensionNode.CreateInstance() + /// method for each node (or TypeExtensionNode.GetInstance() if + /// reuseCachedInstance is set to true). + /// + /// An InvalidOperationException exception is thrown if one of the found + /// objects is not a subclass of the provided type. + /// </remarks> public static T[] GetExtensionObjects<T> (string path, bool reuseCachedInstance) { AddinEngine.CheckInitialized (); return AddinEngine.GetExtensionObjects<T> (path, reuseCachedInstance); } + /// <summary> + /// Extension change event. + /// </summary> + /// <remarks> + /// This event is fired when any extension point in the add-in system changes. + /// The event args object provides the path of the changed extension, although + /// it does not provide information about what changed. Hosts subscribing to + /// this event should get the new list of nodes using a query method such as + /// AddinManager.GetExtensionNodes() and then update whatever needs to be updated. + /// </remarks> public static event ExtensionEventHandler ExtensionChanged { add { AddinEngine.CheckInitialized(); AddinEngine.ExtensionChanged += value; } remove { AddinEngine.CheckInitialized(); AddinEngine.ExtensionChanged -= value; } } + /// <summary> + /// Register a listener of extension node changes. + /// </summary> + /// <param name="path"> + /// Path of the node. + /// </param> + /// <param name="handler"> + /// A handler method. + /// </param> + /// <remarks> + /// Hosts can call this method to be subscribed to an extension change + /// event for a specific path. The event will be fired once for every + /// individual node change. The event arguments include the change type + /// (Add or Remove) and the extension node added or removed. + /// + /// NOTE: The handler will be called for all nodes existing in the path at the moment of registration. + /// </remarks> public static void AddExtensionNodeHandler (string path, ExtensionNodeEventHandler handler) { AddinEngine.CheckInitialized (); AddinEngine.AddExtensionNodeHandler (path, handler); } + /// <summary> + /// Unregister a listener of extension node changes. + /// </summary> + /// <param name="path"> + /// Path of the node. + /// </param> + /// <param name="handler"> + /// A handler method. + /// </param> + /// <remarks> + /// This method unregisters a delegate from the node change event of a path. + /// </remarks> public static void RemoveExtensionNodeHandler (string path, ExtensionNodeEventHandler handler) { AddinEngine.CheckInitialized (); AddinEngine.RemoveExtensionNodeHandler (path, handler); } - + + /// <summary> + /// Register a listener of extension node changes. + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <param name="handler"> + /// A handler method. + /// </param> + /// <remarks> + /// Hosts can call this method to be subscribed to an extension change + /// event for a specific type extension point. The event will be fired once for every + /// individual node change. The event arguments include the change type + /// (Add or Remove) and the extension node added or removed. + /// + /// NOTE: The handler will be called for all nodes existing in the path at the moment of registration. + /// </remarks> public static void AddExtensionNodeHandler (Type instanceType, ExtensionNodeEventHandler handler) { AddinEngine.CheckInitialized (); AddinEngine.AddExtensionNodeHandler (instanceType, handler); } + /// <summary> + /// Unregister a listener of extension node changes. + /// </summary> + /// <param name="instanceType"> + /// Type defining the extension point + /// </param> + /// <param name="handler"> + /// A handler method. + /// </param> public static void RemoveExtensionNodeHandler (Type instanceType, ExtensionNodeEventHandler handler) { AddinEngine.CheckInitialized (); AddinEngine.RemoveExtensionNodeHandler (instanceType, handler); } + /// <summary> + /// Add-in loading error event. + /// </summary> + /// <remarks> + /// This event is fired when there is an error when loading the extension + /// of an add-in, or any other kind of error that may happen when querying extension points. + /// </remarks> public static event AddinErrorEventHandler AddinLoadError { add { AddinEngine.AddinLoadError += value; } remove { AddinEngine.AddinLoadError -= value; } } + /// <summary> + /// Add-in loaded event. + /// </summary> + /// <remarks> + /// Fired after loading an add-in in memory. + /// </remarks> public static event AddinEventHandler AddinLoaded { add { AddinEngine.AddinLoaded += value; } remove { AddinEngine.AddinLoaded -= value; } } + /// <summary> + /// Add-in unload event. + /// </summary> + /// <remarks> + /// Fired when an add-in is unloaded from memory. It may happen an add-in is disabled or uninstalled. + /// </remarks> public static event AddinEventHandler AddinUnloaded { add { AddinEngine.AddinUnloaded += value; } remove { AddinEngine.AddinUnloaded -= value; } diff --git a/Mono.Addins/Mono.Addins/AddinModuleAttribute.cs b/Mono.Addins/Mono.Addins/AddinModuleAttribute.cs index 377073d..83d7b6f 100644 --- a/Mono.Addins/Mono.Addins/AddinModuleAttribute.cs +++ b/Mono.Addins/Mono.Addins/AddinModuleAttribute.cs @@ -28,15 +28,27 @@ using System; namespace Mono.Addins { + /// <summary> + /// Declares an optional add-in module + /// </summary> public class AddinModuleAttribute: Attribute { string assemblyFile; + /// <summary> + /// Initializes the instance. + /// </summary> + /// <param name="assemblyFile"> + /// Relative path to the assembly that implements the optional module + /// </param> public AddinModuleAttribute (string assemblyFile) { this.assemblyFile = assemblyFile; } + /// <summary> + /// Relative path to the assembly that implements the optional module + /// </summary> public string AssemblyFile { get { return this.assemblyFile ?? string.Empty; } set { this.assemblyFile = value; } diff --git a/Mono.Addins/Mono.Addins/AddinRegistry.cs b/Mono.Addins/Mono.Addins/AddinRegistry.cs index c8d5afb..1570206 100644 --- a/Mono.Addins/Mono.Addins/AddinRegistry.cs +++ b/Mono.Addins/Mono.Addins/AddinRegistry.cs @@ -37,6 +37,32 @@ using Mono.Addins.Description; namespace Mono.Addins { + /// <summary> + /// An add-in registry. + /// </summary> + /// <remarks> + /// An add-in registry is a data structure used by the add-in engine to locate add-ins to load. + /// + /// A registry can be configured to look for add-ins in several directories. However, add-ins + /// copied to those directories won't be detected until an explicit add-in scan is requested. + /// The registry can be updated by an application by calling Registry.Update(), or by a user by + /// running the 'mautil' add-in setup tool. + /// + /// The registry has information about the location of every add-in and a timestamp of the last + /// check, so the Update method will only scan new or modified add-ins. An application can + /// add a call to Registry.Update() in the Main method to detect all new add-ins every time the + /// app is started. + /// + /// Every add-in added to the registry is parsed and validated, and if there is any error it + /// will be rejected. The registry is also in charge of scanning the add-in assemblies and look + /// for extensions and other information declared using custom attributes. That information is + /// merged with the manifest information (if there is one) to create a complete add-in + /// description ready to be used at run-time. + /// + /// Mono.Addins allows sharing an add-in registry among several applications. In this context, + /// all applications sharing the registry share the same extension point model, and it is + /// possible to implement add-ins which extend several hosts. + /// </remarks> public class AddinRegistry: IDisposable { AddinDatabase database; @@ -45,10 +71,31 @@ namespace Mono.Addins string currentDomain; string startupDirectory; + /// <summary> + /// Initializes a new instance. + /// </summary> + /// <param name="registryPath"> + /// Location of the add-in registry. + /// </param> + /// <remarks> + /// Creates a new add-in registry located in the provided path. + /// </remarks> public AddinRegistry (string registryPath): this (null, registryPath, null) { } + /// <summary> + /// Initializes a new instance. + /// </summary> + /// <param name="registryPath"> + /// Location of the add-in registry. + /// </param> + /// <param name="startupDirectory"> + /// Location of the application. + /// </param> + /// <remarks> + /// Creates a new add-in registry located in the provided path. + /// </remarks> public AddinRegistry (string registryPath, string startupDirectory): this (null, registryPath, startupDirectory) { } @@ -71,6 +118,16 @@ namespace Mono.Addins currentDomain = AddinDatabase.GlobalDomain; } + /// <summary> + /// Gets the global registry. + /// </summary> + /// <returns> + /// The global registry + /// </returns> + /// <remarks> + /// The global add-in registry is created in "~/.config/mono.addins", + /// and it is the default registry used when none is specified. + /// </remarks> public static AddinRegistry GetGlobalRegistry () { return GetGlobalRegistry (null, null); @@ -105,15 +162,33 @@ namespace Mono.Addins } } + /// <summary> + /// Location of the add-in registry. + /// </summary> public string RegistryPath { get { return basePath; } } + /// <summary> + /// Disposes the add-in engine. + /// </summary> public void Dispose () { database.Shutdown (); } + /// <summary> + /// Returns an add-in from the registry. + /// </summary> + /// <param name="id"> + /// Identifier of the add-in. + /// </param> + /// <returns> + /// The add-in, or 'null' if not found. + /// </returns> + /// <remarks> + /// The add-in identifier may optionally include a version number, for example: "TextEditor.Xml,1.2" + /// </remarks> public Addin GetAddin (string id) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -121,6 +196,23 @@ namespace Mono.Addins return database.GetInstalledAddin (currentDomain, id); } + /// <summary> + /// Returns an add-in from the registry. + /// </summary> + /// <param name="id"> + /// Identifier of the add-in. + /// </param> + /// <param name="exactVersionMatch"> + /// 'true' if the exact add-in version must be found. + /// </param> + /// <returns> + /// The add-in, or 'null' if not found. + /// </returns> + /// <remarks> + /// The add-in identifier may optionally include a version number, for example: "TextEditor.Xml,1.2". + /// In this case, if the exact version is not found and exactVersionMatch is 'false', it will + /// return one than is compatible with the required version. + /// </remarks> public Addin GetAddin (string id, bool exactVersionMatch) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -128,6 +220,12 @@ namespace Mono.Addins return database.GetInstalledAddin (currentDomain, id, exactVersionMatch); } + /// <summary> + /// Gets all add-ins registered in the registry. + /// </summary> + /// <returns> + /// Add-ins registered in the registry. + /// </returns> public Addin[] GetAddins () { if (currentDomain == AddinDatabase.UnknownDomain) @@ -136,6 +234,12 @@ namespace Mono.Addins return (Addin[]) list.ToArray (typeof(Addin)); } + /// <summary> + /// Gets all add-in roots registered in the registry. + /// </summary> + /// <returns> + /// Descriptions of all add-in roots. + /// </returns> public Addin[] GetAddinRoots () { if (currentDomain == AddinDatabase.UnknownDomain) @@ -144,6 +248,22 @@ namespace Mono.Addins return (Addin[]) list.ToArray (typeof(Addin)); } + /// <summary> + /// Loads an add-in description + /// </summary> + /// <param name="progressStatus"> + /// Progress tracker. + /// </param> + /// <param name="file"> + /// Name of the file to load + /// </param> + /// <returns> + /// An add-in description + /// </returns> + /// <remarks> + /// This method loads an add-in description from a file. The file can be an XML manifest or an + /// assembly that implements an add-in. + /// </remarks> public AddinDescription GetAddinDescription (IProgressStatus progressStatus, string file) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -174,6 +294,15 @@ namespace Mono.Addins } } + /// <summary> + /// Reads an XML add-in manifest + /// </summary> + /// <param name="file"> + /// Path to the XML file + /// </param> + /// <returns> + /// An add-in description + /// </returns> public AddinDescription ReadAddinManifestFile (string file) { AddinDescription desc = AddinDescription.Read (file); @@ -183,7 +312,19 @@ namespace Mono.Addins } return desc; } - + + /// <summary> + /// Reads an XML add-in manifest + /// </summary> + /// <param name="reader"> + /// Reader that contains the XML + /// </param> + /// <param name="baseFile"> + /// Base path to use to discover add-in files + /// </param> + /// <returns> + /// An add-in description + /// </returns> public AddinDescription ReadAddinManifestFile (TextReader reader, string baseFile) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -194,6 +335,15 @@ namespace Mono.Addins return desc; } + /// <summary> + /// Checks whether an add-in is enabled. + /// </summary> + /// <param name="id"> + /// Identifier of the add-in. + /// </param> + /// <returns> + /// 'true' if the add-in is enabled. + /// </returns> public bool IsAddinEnabled (string id) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -201,6 +351,16 @@ namespace Mono.Addins return database.IsAddinEnabled (currentDomain, id); } + /// <summary> + /// Enables an add-in. + /// </summary> + /// <param name="id"> + /// Identifier of the add-in + /// </param> + /// <remarks> + /// If the enabled add-in depends on other add-ins which are disabled, + /// those will automatically be enabled too. + /// </remarks> public void EnableAddin (string id) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -208,6 +368,17 @@ namespace Mono.Addins database.EnableAddin (currentDomain, id, true); } + /// <summary> + /// Disables an add-in. + /// </summary> + /// <param name="id"> + /// Identifier of the add-in. + /// </param> + /// <remarks> + /// When an add-in is disabled, all extension points it defines will be ignored + /// by the add-in engine. Other add-ins which depend on the disabled add-in will + /// also automatically be disabled. + /// </remarks> public void DisableAddin (string id) { if (currentDomain == AddinDatabase.UnknownDomain) @@ -215,11 +386,17 @@ namespace Mono.Addins database.DisableAddin (currentDomain, id); } + /// <summary> + /// Internal use only + /// </summary> public void DumpFile (string file) { Mono.Addins.Serialization.BinaryXmlReader.DumpFile (file); } + /// <summary> + /// Resets the configuration files of the registry + /// </summary> public void ResetConfiguration () { database.ResetConfiguration (); @@ -231,16 +408,53 @@ namespace Mono.Addins currentDomain = database.GetFolderDomain (null, startupDirectory); } + /// <summary> + /// Updates the add-in registry. + /// </summary> + /// <remarks> + /// This method must be called after modifying, installing or uninstalling add-ins. + /// + /// When calling Update, every add-in added to the registry is parsed and validated, + /// and if there is any error it will be rejected. It will also cache add-in information + /// needed at run-time. + /// + /// If during the update operation the registry finds new add-ins or detects that some + /// add-ins have been deleted, the loaded extension points will be updated to include + /// or exclude extension nodes from those add-ins. + /// </remarks> public void Update () { Update (new ConsoleProgressStatus (false)); } + /// <summary> + /// Updates the add-in registry. + /// </summary> + /// <param name="monitor"> + /// Progress monitor to keep track of the update operation. + /// </param> + /// <remarks> + /// This method must be called after modifying, installing or uninstalling add-ins. + /// + /// When calling Update, every add-in added to the registry is parsed and validated, + /// and if there is any error it will be rejected. It will also cache add-in information + /// needed at run-time. + /// + /// If during the update operation the registry finds new add-ins or detects that some + /// add-ins have been deleted, the loaded extension points will be updated to include + /// or exclude extension nodes from those add-ins. + /// </remarks> public void Update (IProgressStatus monitor) { database.Update (monitor, currentDomain); } + /// <summary> + /// Regenerates the cached data of the add-in registry. + /// </summary> + /// <param name="monitor"> + /// Progress monitor to keep track of the rebuild operation. + /// </param> public void Rebuild (IProgressStatus monitor) { database.Repair (monitor, currentDomain); @@ -268,6 +482,14 @@ namespace Mono.Addins database.ParseAddin (progressStatus, currentDomain, file, outFile, true); } + /// <summary> + /// Gets the default add-ins folder of the registry. + /// </summary> + /// <remarks> + /// For every add-in registry there is an add-in folder where the registry will look for add-ins by default. + /// This folder is an "addins" subdirectory of the directory where the repository is located. In most cases, + /// this folder will only contain .addins files referencing other more convenient locations for add-ins. + /// </remarks> public string DefaultAddinsFolder { get { return Path.Combine (basePath, "addins"); } } @@ -325,6 +547,7 @@ namespace Mono.Addins return true; } + [Obsolete] public static string[] GetRegisteredStartupFolders (string registryPath) { string dbDir = Path.Combine (registryPath, "addin-db-" + AddinDatabase.VersionTag); |