Adding code comments

--HG--
branch : 1.x

src/Orchard/ContentManagement/IContentManager.cs

@@ -4,16 +4,54 @@ using Orchard.ContentManagement.MetaData.Models;
 using Orchard.Indexing;
 
 namespace Orchard.ContentManagement {
+    /// <summary>
+    /// Content management functionality to deal with Orchard content items and their parts
+    /// </summary>
     public interface IContentManager : IDependency {
         IEnumerable<ContentTypeDefinition> GetContentTypeDefinitions();
 
+
+        /// <summary>
+        /// Instantiates a new content item with the specified type
+        /// </summary>
+        /// <remarks>
+        /// The content item is not yet persisted!
+        /// </remarks>
+        /// <param name="contentType">The name of the content type</param>
         ContentItem New(string contentType);
         
+
+        /// <summary>
+        /// Creates (persists) a new content item
+        /// </summary>
+        /// <param name="contentItem">The content item instance filled with all necessary data</param>
         void Create(ContentItem contentItem);
+
+        /// <summary>
+        /// Creates (persists) a new content item with the specified version
+        /// </summary>
+        /// <param name="contentItem">The content item instance filled with all necessary data</param>
+        /// <param name="options">The version to create the item with</param>
         void Create(ContentItem contentItem, VersionOptions options);
 
+
+        /// <summary>
+        /// Gets the content item with the specified id
+        /// </summary>
+        /// <param name="id">Numeric id of the content item</param>
         ContentItem Get(int id);
+
+        /// <summary>
+        /// Gets the content item with the specified id and version
+        /// </summary>
+        /// <param name="id">Numeric id of the content item</param>
+        /// <param name="options">The version option</param>
         ContentItem Get(int id, VersionOptions options);
+
+        /// <summary>
+        /// Gets all versions of the content item specified with its id
+        /// </summary>
+        /// <param name="id">Numeric id of the content item</param>
         IEnumerable<ContentItem> GetAllVersions(int id);
 
         IEnumerable<T> GetMany<T>(IEnumerable<int> ids, VersionOptions options, QueryHints hints) where T : class, IContent;
@@ -27,7 +65,14 @@ namespace Orchard.ContentManagement {
         XElement Export(ContentItem contentItem);
         void Import(XElement element, ImportContentSession importContentSession);
 
+        /// <summary>
+        /// Flushes all pending content items to the persistance layer
+        /// </summary>
         void Flush();
+
+        /// <summary>
+        /// Query for arbitrary content items
+        /// </summary>
         IContentQuery<ContentItem> Query();
         IHqlQuery HqlQuery();
 
@@ -37,8 +82,31 @@ namespace Orchard.ContentManagement {
         GroupInfo GetEditorGroupInfo(IContent contentItem, string groupInfoId);
         GroupInfo GetDisplayGroupInfo(IContent contentItem, string groupInfoId);
 
+
+        /// <summary>
+        /// Builds the display shape of the specified content item
+        /// </summary>
+        /// <param name="content">The content item to use</param>
+        /// <param name="displayType">The display type (e.g. Summary, Detail) to use</param>
+        /// <param name="groupId">Id of the display group (stored in the content item's metadata)</param>
+        /// <returns>The display shape</returns>
         dynamic BuildDisplay(IContent content, string displayType = "", string groupId = "");
+
+        /// <summary>
+        /// Builds the editor shape of the specified content item
+        /// </summary>
+        /// <param name="content">The content item to use</param>
+        /// <param name="groupId">Id of the editor group (stored in the content item's metadata)</param>
+        /// <returns>The editor shape</returns>
         dynamic BuildEditor(IContent content, string groupId = "");
+
+        /// <summary>
+        /// Updates the content item and its editor shape with new data through an IUpdateModel
+        /// </summary>
+        /// <param name="content">The content item to update</param>
+        /// <param name="updater">The updater to use for updating</param>
+        /// <param name="groupId">Id of the editor group (stored in the content item's metadata)</param>
+        /// <returns>The updated editor shape</returns>
         dynamic UpdateEditor(IContent content, IUpdateModel updater, string groupId = "");
     }
 

src/Orchard/IOrchardServices.cs

@@ -4,12 +4,29 @@ using Orchard.Security;
 using Orchard.UI.Notify;
 
 namespace Orchard {
+    /// <summary>
+    /// Most important parts of the Orchard API
+    /// </summary>
     public interface IOrchardServices : IDependency {
         IContentManager ContentManager { get; }
         ITransactionManager TransactionManager { get; }
         IAuthorizer Authorizer { get; }
         INotifier Notifier { get; }
+
+        /// <summary>
+        /// Shape factory
+        /// </summary>
+        /// <example>
+        /// dynamic shape = New.ShapeName(Parameter: myVar)
+        /// 
+        /// Now the shape can used in various ways, like returning it from a controller action
+        /// inside a ShapeResult or adding it to the Layout shape.
+        /// 
+        /// Inside the shape template (ShapeName.cshtml) the parameters can be accessed as follows:
+        /// @Model.Parameter
+        /// </example>
         dynamic New { get; }
+
         WorkContext WorkContext { get; }
     }
 }

src/Orchard/Security/Authorizer.cs

@@ -4,9 +4,31 @@ using Orchard.Security.Permissions;
 using Orchard.UI.Notify;
 
 namespace Orchard.Security {
+    /// <summary>
+    /// Authorization services for the current user
+    /// </summary>
     public interface IAuthorizer : IDependency {
+        /// <summary>
+        /// Authorize the current user against a permission
+        /// </summary>
+        /// <param name="permission">A permission to authorize against</param>
         bool Authorize(Permission permission);
+
+        /// <summary>
+        /// Authorize the current user against a permission; if authorization fails, the specified
+        /// message will be displayed
+        /// </summary>
+        /// <param name="permission">A permission to authorize against</param>
+        /// <param name="message">A localized message to display if authorization fails</param>
         bool Authorize(Permission permission, LocalizedString message);
+
+        /// <summary>
+        /// Authorize the current user against a permission for a specified content item;
+        /// if authorization fails, the specified message will be displayed
+        /// </summary>
+        /// <param name="permission">A permission to authorize against</param>
+        /// <param name="content">A content item the permission will be checked for</param>
+        /// <param name="message">A localized message to display if authorization fails</param>
         bool Authorize(Permission permission, IContent content, LocalizedString message);
     }
 

src/Orchard/UI/Notify/Notifier.cs

@@ -3,8 +3,25 @@ using Orchard.Localization;
 using Orchard.Logging;
 
 namespace Orchard.UI.Notify {
+    /// <summary>
+    /// Notification manager for UI notifications
+    /// </summary>
+    /// <remarks>
+    /// Where such notifications are displayed depends on the theme used. Default themes contain a 
+    /// Messages zone for this.
+    /// </remarks>
     public interface INotifier : IDependency {
+        /// <summary>
+        /// Adds a new UI notification
+        /// </summary>
+        /// <param name="type">
+        /// The type of the notification (notifications with different types can be displayed differently)</param>
+        /// <param name="message">A localized message to display</param>
         void Add(NotifyType type, LocalizedString message);
+
+        /// <summary>
+        /// Get all notifications added
+        /// </summary>
         IEnumerable<NotifyEntry> List();
     }
 

src/Orchard/UI/Notify/NotifierExtensions.cs

@@ -2,12 +2,29 @@ using Orchard.Localization;
 
 namespace Orchard.UI.Notify {
     public static class NotifierExtensions {
+        /// <summary>
+        /// Adds a new UI notification of type Information
+        /// </summary>
+        /// <seealso cref="Orchard.UI.Notify.INotifier.Add()"/>
+        /// <param name="message">A localized message to display</param>
         public static void Information(this INotifier notifier, LocalizedString message) {
             notifier.Add(NotifyType.Information, message);
         }
+
+        /// <summary>
+        /// Adds a new UI notification of type Warning
+        /// </summary>
+        /// <seealso cref="Orchard.UI.Notify.INotifier.Add()"/>
+        /// <param name="message">A localized message to display</param>
         public static void Warning(this INotifier notifier, LocalizedString message) {
             notifier.Add(NotifyType.Warning, message);
         }
+
+        /// <summary>
+        /// Adds a new UI notification of type Error
+        /// </summary>
+        /// <seealso cref="Orchard.UI.Notify.INotifier.Add()"/>
+        /// <param name="message">A localized message to display</param>
         public static void Error(this INotifier notifier, LocalizedString message) {
             notifier.Add(NotifyType.Error, message);
         }

src/Orchard/UI/Resources/RequireSettings.cs

@@ -24,14 +24,25 @@ namespace Orchard.UI.Resources {
             get { return _attributes != null && _attributes.Any(a => a.Value != null); }
         }
 
+        /// <summary>
+        /// The resource will be displayed in the head of the page
+        /// </summary>
         public RequireSettings AtHead() {
             return AtLocation(ResourceLocation.Head);
         }
 
+        /// <summary>
+        /// The resource will be displayed at the foot of the page
+        /// </summary>
+        /// <returns></returns>
         public RequireSettings AtFoot() {
             return AtLocation(ResourceLocation.Foot);
         }
 
+        /// <summary>
+        /// The resource will be displayed at the specified location
+        /// </summary>
+        /// <param name="location">The location where the resource should be displayed</param>
         public RequireSettings AtLocation(ResourceLocation location) {
             // if head is specified it takes precedence since it's safer than foot
             Location = (ResourceLocation)Math.Max((int)Location, (int)location);

src/Orchard/UI/Resources/ResourceRegister.cs

@@ -25,6 +25,10 @@ namespace Orchard.UI.Resources {
         protected IResourceManager ResourceManager { get; private set; }
         protected string ResourceType { get; private set; }
 
+        /// <summary>
+        /// Includes a resource with the specified path
+        /// </summary>
+        /// <param name="resourcePath">The relative or absolute path of the resource</param>
         public RequireSettings Include(string resourcePath) {
             if (resourcePath == null) {
                 throw new ArgumentNullException("resourcePath");
@@ -32,6 +36,11 @@ namespace Orchard.UI.Resources {
             return ResourceManager.Include(ResourceType, resourcePath, null, ResourceDefinition.GetBasePathFromViewPath(ResourceType, _viewVirtualPath));
         }
 
+        /// <summary>
+        /// Includes a resource with the specified path
+        /// </summary>
+        /// <param name="resourceDebugPath">The relative or absolute path of the resource to be used in debug mode</param>
+        /// <param name="resourcePath">The relative or absolute path of the resource</param>
         public RequireSettings Include(string resourceDebugPath, string resourcePath) {
             if (resourcePath == null) {
                 throw new ArgumentNullException("resourcePath");
@@ -39,6 +48,15 @@ namespace Orchard.UI.Resources {
             return ResourceManager.Include(ResourceType, resourcePath, resourceDebugPath, ResourceDefinition.GetBasePathFromViewPath(ResourceType, _viewVirtualPath));
         }
 
+        /// <summary>
+        /// Includes a resource that is already defined in a resource manifest
+        /// </summary>
+        /// <remarks>
+        /// You can define resources in resource manifest files with ResourceManifestBuilder.
+        /// For examples take a look at any ResourceManifest.cs file.
+        /// </remarks>
+        /// <param name="resourceName"></param>
+        /// <returns></returns>
         public virtual RequireSettings Require(string resourceName) {
             if (resourceName == null) {
                 throw new ArgumentNullException("resourceName");
@@ -55,7 +73,15 @@ namespace Orchard.UI.Resources {
         protected ScriptRegister(IViewDataContainer container, IResourceManager resourceManager) : base(container, resourceManager, "script") {
         }
 
+        /// <summary>
+        /// Uses scripts that were registered to appear in the head of the page
+        /// </summary>
         public abstract IDisposable Head();
+
+        /// <summary>
+        /// Uses scripts that were registered to appear at the foot of the page
+        /// </summary>
+        /// <returns></returns>
         public abstract IDisposable Foot();
     }
 }

src/Orchard/WorkContext.cs

@@ -4,38 +4,73 @@ using Orchard.Security;
 using Orchard.Settings;
 
 namespace Orchard {
+    /// <summary>
+    /// A work context for work context scope
+    /// </summary>
     public abstract class WorkContext {
+        /// <summary>
+        /// Resolves a registered dependency type
+        /// </summary>
+        /// <typeparam name="T">The type of the dependency</typeparam>
+        /// <returns>An instance of the dependency if it could be resolved</returns>
         public abstract T Resolve<T>();
+
+        /// <summary>
+        /// Tries to resolve a registered dependency type
+        /// </summary>
+        /// <typeparam name="T">The type of the dependency</typeparam>
+        /// <param name="service">An instance of the dependency if it could be resolved</param>
+        /// <returns>True if the dependency could be resolved, false otherwise</returns>
         public abstract bool TryResolve<T>(out T service);
 
+
         public abstract T GetState<T>(string name);
         public abstract void SetState<T>(string name, T value);
 
+
+        /// <summary>
+        /// The http context corresponding to the work context
+        /// </summary>
         public HttpContextBase HttpContext {
             get { return GetState<HttpContextBase>("HttpContext"); }
             set { SetState("HttpContext", value); }
         }
 
+        /// <summary>
+        /// The Layout shape corresponding to the work context
+        /// </summary>
         public dynamic Layout {
             get { return GetState<object>("Layout"); }
             set { SetState("Layout", value); }
         }
 
+        /// <summary>
+        /// Settings of the site corresponding to the work context
+        /// </summary>
         public ISite CurrentSite {
             get { return GetState<ISite>("CurrentSite"); }
             set { SetState("CurrentSite", value); }
         }
 
+        /// <summary>
+        /// The user, if there is any corresponding to the work context
+        /// </summary>
         public IUser CurrentUser {
             get { return GetState<IUser>("CurrentUser"); }
             set { SetState("CurrentUser", value); }
         }
 
+        /// <summary>
+        /// The theme used in the work context
+        /// </summary>
         public ExtensionDescriptor CurrentTheme {
             get { return GetState<ExtensionDescriptor>("CurrentTheme"); }
             set { SetState("CurrentTheme", value); }
         }
 
+        /// <summary>
+        /// Active culture of the work context
+        /// </summary>
         public string CurrentCulture {
             get { return GetState<string>("CurrentCulture"); }
             set { SetState("CurrentCulture", value); }