Merge pull request #1400 from 2sic-forks/dev

More documentation - almost all Models done #1382

Oqtane.Shared/Models/ConnectionStringField.cs

@@ -1,13 +1,28 @@
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Helper class for input fields in the setup of the SQL connection
+    /// </summary>
     public class ConnectionStringField
     {
+        /// <summary>
+        /// Simple to understand field name / label
+        /// </summary>
         public string FriendlyName { get; set; }
 
+        /// <summary>
+        /// Instructions / help for the user
+        /// </summary>
         public string HelpText { get; set; }
 
+        /// <summary>
+        /// Property / Setting name which will be filled in by the user. Typically something like `Server`, `Port` etc.
+        /// </summary>
         public string Name { get; set; }
 
+        /// <summary>
+        /// Initial value used in the UI and probably later also the user input that was given.
+        /// </summary>
         public string Value { get; set; }
     }
 }

Oqtane.Shared/Models/Culture.cs

@@ -1,11 +1,26 @@
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Culture information describing a Culture
+    /// </summary>
     public class Culture
     {
+        /// <summary>
+        /// Short code like `en` or `en-US`
+        /// </summary>
         public string Name { get; set; }
 
+        /// <summary>
+        /// Nice name for the user, like `English (United States)`
+        /// </summary>
         public string DisplayName { get; set; }
 
+        /// <summary>
+        /// Information if this is the default culture. 
+        /// </summary>
+        /// <remarks>
+        /// Not sure if this is actually valid, as ATM there is no setting to configure a _default_ culture
+        /// </remarks>
         public bool IsDefault { get; set; }
     }
 }

Oqtane.Shared/Models/Database.cs

@@ -1,15 +1,33 @@
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Information about a Database used in the current Oqtane installation
+    /// </summary>
     public class Database
     {
+        /// <summary>
+        /// Friendly name for the Admin to identify the DB
+        /// </summary>
         public string FriendlyName { get; set; }
 
+        /// <summary>
+        /// Name of the Database
+        /// </summary>
         public string Name { get; set; }
 
+        /// <summary>
+        /// Namespace & name of the UI control to configure this database, like `Oqtane.Installer.Controls.SqlServerConfig, Oqtane.Client`
+        /// </summary>
         public string ControlType { get; set; }
 
+        /// <summary>
+        /// Type of DB using the full namespace, like `Oqtane.Database.SqlServer.SqlServerDatabase, Oqtane.Database.SqlServer`
+        /// </summary>
         public string DBType { get; set; }
 
+        /// <summary>
+        /// Software package responsible for using this DB - like `Oqtane.Database.MySQL`
+        /// </summary>
         public string Package { get; set; }
     }
 }

Oqtane.Shared/Models/Installation.cs

@@ -1,8 +1,20 @@
-namespace Oqtane.Models
+namespace Oqtane.Models
 {
+    /// <summary>
+    /// Internal message used internally during installation.
+    ///
+    /// Each part of the installation will return the status / message when installing.
+    /// </summary>
     public class Installation 
     {
+        /// <summary>
+        /// Status if everything worked. 
+        /// </summary>
         public bool Success { get; set; }
+
+        /// <summary>
+        /// Message or error in case something failed.
+        /// </summary>
         public string Message { get; set; }
     }
 }

Oqtane.Shared/Models/Job.cs

@@ -1,25 +1,88 @@
-using System;
+using System;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Definition of a Job / Task which is run on the server.
+    /// When Jobs run, they create a <see cref="JobLog"/>
+    /// </summary>
     public class Job : IAuditable
     {
+        /// <summary>
+        /// Internal ID
+        /// </summary>
         public int JobId { get; set; }
+
+        /// <summary>
+        /// Name for simple identification
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// What kind of Job this is 
+        /// </summary>
         public string JobType { get; set; }
+
+        /// <summary>
+        /// Unit used in how often the job should run - expects a character like `m` (minutes), `H` (hours) etc.
+        /// </summary>
         public string Frequency { get; set; }
+
+        /// <summary>
+        /// How often the Job should run - see also <see cref="Frequency"/>
+        /// </summary>
         public int Interval { get; set; }
+
+        /// <summary>
+        /// When the Job is to be run the first time. See also <see cref="EndDate"/>.
+        /// </summary>
         public DateTime? StartDate { get; set; }
+
+
+        /// <summary>
+        /// When the job is to be run the last time. See also <see cref="StartDate"/>.
+        /// </summary>
         public DateTime? EndDate { get; set; }
+
+        /// <summary>
+        /// Determines if the Job is activated / enabled.
+        /// </summary>
         public bool IsEnabled { get; set; }
+
+        /// <summary>
+        /// If the Job has ever started running
+        /// </summary>
         public bool IsStarted { get; set; }
+
+        /// <summary>
+        /// If the Job is executing right now. 
+        /// </summary>
         public bool IsExecuting { get; set; }
+
+        /// <summary>
+        /// When the Job will run again next time.
+        /// </summary>
         public DateTime? NextExecution { get; set; }
+
+        /// <summary>
+        /// Todo: todoc - unsure what this does
+        /// </summary>
         public int RetentionHistory { get; set; }
 
+        #region IAuditable Properties
+
+        /// <inheritdoc/>
         public string CreatedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime CreatedOn { get; set; }
+
+        /// <inheritdoc/>
         public string ModifiedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime ModifiedOn { get; set; }
+
+        #endregion
     }
 }

Oqtane.Shared/Models/JobLog.cs

@@ -1,16 +1,48 @@
-using System;
+using System;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Log / Journal of <see cref="Job"/>s executed.
+    /// </summary>
     public class JobLog
     {
+        /// <summary>
+        /// Internal ID
+        /// </summary>
         public int JobLogId { get; set; }
+
+        /// <summary>
+        /// Reference to the <see cref="Job"/> which was run
+        /// </summary>
         public int JobId { get; set; }
+
+        /// <summary>
+        /// Timestamp when the <see cref="Job"/> started. 
+        /// </summary>
         public DateTime StartDate { get; set; }
+
+        /// <summary>
+        /// Timestamp when the <see cref="Job"/> ended. 
+        /// </summary>
         public DateTime? FinishDate { get; set; }
+
+        /// <summary>
+        /// Success information. 
+        /// </summary>
         public bool? Succeeded { get; set; }
+
+        /// <summary>
+        /// Additional protocol information that was left after the <see cref="Job"/> ran.
+        /// </summary>
         public string Notes { get; set; }
 
+        /// <summary>
+        /// Reference to the Job. 
+        /// </summary>
+        /// <remarks>
+        /// It's not clear if this is always populated. 
+        /// </remarks>
         public Job Job { get; set; }
     }
 }

Oqtane.Shared/Models/Language.cs

@@ -20,12 +20,12 @@ namespace Oqtane.Models
         public int? SiteId { get; set; }
 
         /// <summary>
-        /// Language Name
+        /// Language Name - corresponds to <see cref="Culture.DisplayName"/>, _not_ <see cref="Culture.Name"/>
         /// </summary>
         public string Name { get; set; }
 
         /// <summary>
-        /// Language / Culture code, like 'en-US'
+        /// Language / Culture code, like 'en-US' - corresponds to <see cref="Culture.Name"/>
         /// </summary>
         public string Code { get; set; }
 

Oqtane.Shared/Models/ModuleContent.cs

@@ -1,9 +1,23 @@
-namespace Oqtane.Models
+namespace Oqtane.Models
 {
+    /// <summary>
+    /// Generic Model for Module-Contents to enable Import/Export of the Module-Data
+    /// </summary>
     public class ModuleContent
     {
+        /// <summary>
+        /// Reference to a <see cref="ModuleDefinition"/> for which this content is relevant. 
+        /// </summary>
         public string ModuleDefinitionName { get; set; }
+
+        /// <summary>
+        /// Version of the <see cref="ModuleDefinition"/> which is used here. _It's not the version of the Content_
+        /// </summary>
         public string Version { get; set; }
+
+        /// <summary>
+        /// Serialized Content of the module for import/export.
+        /// </summary>
         public string Content { get; set; }
     }
 }

Oqtane.Shared/Models/ModuleDefinition.cs

@@ -52,7 +52,15 @@ namespace Oqtane.Models
         /// Module description for admin dialogs.
         /// </summary>
         public string Description { get; set; }
+
+        /// <summary>
+        /// Categories this Module will be shown in (in the admin-dialogs)
+        /// </summary>
         public string Categories { get; set; }
+
+        /// <summary>
+        /// Version information of this Module based on the DLL / NuGet package.
+        /// </summary>
         public string Version { get; set; }
 
         #region IAuditable Properties

Oqtane.Shared/Models/Notification.cs

@@ -3,25 +3,95 @@ using System.ComponentModel.DataAnnotations.Schema;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Notification for a User - usually meant to be sent as an E-Mail.
+    /// </summary>
     public class Notification : IDeletable
     {
+        /// <summary>
+        /// Internal ID
+        /// </summary>
         public int NotificationId { get; set; }
+
+        /// <summary>
+        /// Reference to the <see cref="Site"/> on which the Notification was created. 
+        /// </summary>
         public int SiteId { get; set; }
+
+        /// <summary>
+        /// Creator <see cref="User"/> ID
+        /// </summary>
         public int? FromUserId { get; set; }
+
+        /// <summary>
+        /// Nice Name of the Creator
+        /// </summary>
         public string FromDisplayName { get; set; }
+
+        /// <summary>
+        /// Creator E-Mail
+        /// </summary>
         public string FromEmail { get; set; }
+
+        /// <summary>
+        /// Recipient <see cref="User"/> ID - nullable, as Recipient could be someone that's not a user. 
+        /// </summary>
         public int? ToUserId { get; set; }
+
+        /// <summary>
+        /// Recipient Nice-Name.
+        /// </summary>
         public string ToDisplayName { get; set; }
+
+        /// <summary>
+        /// Recipient Mail
+        /// </summary>
         public string ToEmail { get; set; }
+
+        /// <summary>
+        /// Reference to an optional Parent <see cref="Notification"/> - in case it's a kind of thread with reply-messages.
+        /// </summary>
         public int? ParentId { get; set; }
+
+        /// <summary>
+        /// Message Subject.
+        /// </summary>
         public string Subject { get; set; }
+
+        /// <summary>
+        /// Body / Contents of this Notification
+        /// </summary>
         public string Body { get; set; }
+
+        /// <summary>
+        /// When the notification was created. 
+        /// </summary>
         public DateTime CreatedOn { get; set; }
+
+        /// <summary>
+        /// If it has been delivered. See also <see cref="DeliveredOn"/>.
+        /// </summary>
         public bool IsDelivered { get; set; }
+
+        /// <summary>
+        /// When the Notification was sent/delivered.
+        /// </summary>
         public DateTime? DeliveredOn { get; set; }
+
+        #region IDeletable
+        
+        /// <inheritdoc />
         public string DeletedBy { get; set; }
+        /// <inheritdoc />
         public DateTime? DeletedOn { get; set; }
+        /// <inheritdoc />
         public bool IsDeleted { get; set; }
+
+        #endregion
+
+        /// <summary>
+        /// When the Notification _should_ be sent. See also <see cref="DeliveredOn"/>
+        /// </summary>
         public DateTime? SendOn { get; set; }
 
         public Notification() {}

Oqtane.Shared/Models/Package.cs

@@ -1,12 +1,39 @@
-namespace Oqtane.Models
+namespace Oqtane.Models
 {
+    /// <summary>
+    /// A software Package which is like an Oqtane Plugin / Extension.
+    /// This is used for creating lists from NuGet to offer for installation. 
+    /// </summary>
     public class Package
     {
+        /// <summary>
+        /// ID of the Package. Usually constructed of the Namespace.
+        /// </summary>
         public string PackageId { get; set; }
+
+        /// <summary>
+        /// Name of the package - may contains part or the entire Namespace.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// Nice description of the Package. 
+        /// </summary>
         public string Description { get; set; }
+
+        /// <summary>
+        /// Owner / Creator of the package - usually retrieved from NuGet.
+        /// </summary>
         public string Owner { get; set; }
+
+        /// <summary>
+        /// Version as defined in the NuGet package. 
+        /// </summary>
         public string Version { get; set; }
+
+        /// <summary>
+        /// Download count on NuGet to show how popular the package is. 
+        /// </summary>
         public long Downloads { get; set; }
     }
 }

Oqtane.Shared/Models/Permission.cs

@@ -1,23 +1,79 @@
-using System;
+using System;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Permission information for anything in Oqtane.
+    /// Things in Oqtane are identified as Entities, so anything that can be identified can be described here. 
+    /// </summary>
     public class Permission : IAuditable
     {
+        /// <summary>
+        /// Internal ID storing this information.
+        /// </summary>
         public int PermissionId { get; set; }
+
+        /// <summary>
+        /// Reference to the <see cref="Site"/> which contains both the target Entity and permissions. 
+        /// </summary>
         public int SiteId { get; set; }
+
+        /// <summary>
+        /// Name of the Entity these permissions apply to. 
+        /// </summary>
         public string EntityName { get; set; }
+
+        /// <summary>
+        /// ID of the Entity these permissions apply to. 
+        /// </summary>
         public int EntityId { get; set; }
+
+        /// <summary>
+        /// What this permission is called.
+        /// TODO: todoc - must clarify what exactly this means, I assume any module can give it's own names for Permissions
+        /// </summary>
         public string PermissionName { get; set; }
+
+        /// <summary>
+        /// <see cref="Role"/> this permission applies to. So if all users in the Role _Customers_ have this permission, then it would reference that Role.
+        /// If null, then the permission doesn't target a role but probably a <see cref="User"/> (see <see cref="UserId"/>).
+        /// </summary>
         public int? RoleId { get; set; }
+
+
+        /// <summary>
+        /// <see cref="User"/> this permission applies to.  
+        /// If null, then the permission doesn't target a User but probably a <see cref="Role"/> (see <see cref="RoleId"/>).
+        /// </summary>
         public int? UserId { get; set; }
+
+        /// <summary>
+        /// Determines if Authorization is sufficient to receive this permission.
+        /// </summary>
         public bool IsAuthorized { get; set; }
 
+        #region IAuditable Properties
+
+        /// <inheritdoc/>
         public string CreatedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime CreatedOn { get; set; }
+
+        /// <inheritdoc/>
         public string ModifiedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime ModifiedOn { get; set; }
 
+        #endregion
+
+        /// <summary>
+        /// Reference to the <see cref="Role"/> based on the <see cref="RoleId"/> - can be nullable.
+        /// </summary>
+        /// <remarks>
+        /// It's not certain if this will always be populated. TODO: todoc/verify
+        /// </remarks>
         public Role Role { get; set; }
 
         public Permission()

Oqtane.Shared/Models/PermissionString.cs

@@ -1,8 +1,18 @@
-namespace Oqtane.Models
+namespace Oqtane.Models
 {
+    /// <summary>
+    /// Use this to define a <see cref="PermissionName"/> which addresses a set of multiple permissions.
+    /// </summary>
     public class PermissionString
     {
+        /// <summary>
+        /// A term describing a set of permissions
+        /// </summary>
         public string PermissionName { get; set; }
+
+        /// <summary>
+        /// The permissions addressed with this name
+        /// </summary>
         public string Permissions { get; set; }
     }
 }

Oqtane.Shared/Models/Profile.cs

@@ -2,24 +2,87 @@ using System;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// A single Profile Property information of a <see cref="User"/>.  
+    /// So a user will have many of these to fully describe his Profile. 
+    /// </summary>
     public class Profile : IAuditable
     {
+        /// <summary>
+        /// Internal ID
+        /// </summary>
         public int ProfileId { get; set; }
+
+        /// <summary>
+        /// Reference to the <see cref="Site"/>.
+        /// It's nullable, probably because certain users like Super-Users don't specifically belong to any site.
+        /// </summary>
         public int? SiteId { get; set; }
+
+        /// <summary>
+        /// Name of the Profile-Property. _NOT_ the User-Name.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// Title (label) of the Profile Property.
+        /// </summary>
         public string Title { get; set; }
+
+        /// <summary>
+        /// Description of the Property for the UI.
+        /// </summary>
         public string Description { get; set; }
+
+        /// <summary>
+        /// Category of this Profile-Property for grouping etc.
+        /// </summary>
         public string Category { get; set; }
+
+        /// <summary>
+        /// Order of the Property in the list of Profile-Properties.
+        /// </summary>
         public int ViewOrder { get; set; }
+
+        /// <summary>
+        /// Limits the input length of the property. 
+        /// </summary>
         public int MaxLength { get; set; }
+
+        /// <summary>
+        /// Initial/default value of this Property. 
+        /// </summary>
         public string DefaultValue { get; set; }
+
+        /// <summary>
+        /// Some Profile Properties are required - marked with this field.
+        /// </summary>
         public bool IsRequired { get; set; }
+
+        /// <summary>
+        /// Some Profile Properties are private, meaning other users won't see them. 
+        /// </summary>
         public bool IsPrivate { get; set; }
+
+        /// <summary>
+        /// This gives possible values for dropdown input fields. 
+        /// </summary>
         public string Options { get; set; }
 
+        #region IAuditable Properties
+
+        /// <inheritdoc/>
         public string CreatedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime CreatedOn { get; set; }
+
+        /// <inheritdoc/>
         public string ModifiedBy { get; set; }
+
+        /// <inheritdoc/>
         public DateTime ModifiedOn { get; set; }
+
+        #endregion
     }
 }

Oqtane.Shared/Models/Resource.cs

@@ -2,14 +2,45 @@ using Oqtane.Shared;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Resource Objects describe a JavaScript or CSS file which is needed by the Module to work. 
+    /// </summary>
     public class Resource
     {
+        /// <summary>
+        /// A <see cref="ResourceType"/> so the Interop can properly create `script` or `link` tags
+        /// </summary>
         public ResourceType ResourceType { get; set; }
+
+        /// <summary>
+        /// Path to the resources. 
+        /// </summary>
         public string Url { get; set; }
+
+        /// <summary>
+        /// Integrity checks to increase the security of resources accessed. Especially common in CDN resources. 
+        /// </summary>
         public string Integrity { get; set; }
+
+        /// <summary>
+        /// Cross-Origin rules for this Resources. Usually `anonymous`
+        /// </summary>
         public string CrossOrigin { get; set; }
+
+        /// <summary>
+        /// Bundle ID in case this Resource belongs to a set of Resources, which may have already been loaded using LoadJS
+        /// </summary>
         public string Bundle { get; set; }
+
+        /// <summary>
+        /// Determines if the Resource is global, meaning that the entire solution uses it or just some modules.
+        /// TODO: VERIFY that this explanation is correct.
+        /// </summary>
         public ResourceDeclaration Declaration { get; set; }
+
+        /// <summary>
+        /// If the Resource should be included in the `head` of the HTML document or the `body`
+        /// </summary>
         public ResourceLocation Location { get; set; }
     }
 }

Oqtane.Shared/Models/Theme.cs

@@ -3,6 +3,9 @@ using System.Collections.Generic;
 
 namespace Oqtane.Models
 {
+    /// <summary>
+    /// Information about a Theme in Oqtane.
+    /// </summary>
     public class Theme
     {
         public Theme()
@@ -20,14 +23,47 @@ namespace Oqtane.Models
             PackageName = "";
         }
 
+        /// <summary>
+        /// Full Namespace / Identifier of the Theme.
+        /// </summary>
         public string ThemeName { get; set; }
+
+        /// <summary>
+        /// Nice Name of the Theme.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// Version as determined by the DLL / NuGet Package.
+        /// </summary>
         public string Version { get; set; }
+
+        /// <summary>
+        /// Author / Creator of the Theme. 
+        /// </summary>
         public string Owner { get; set; }
+
+        /// <summary>
+        /// URL (in NuGet) of the Theme
+        /// </summary>
         public string Url { get; set; }
+
+        /// <summary>
+        /// Author Contact information
+        /// </summary>
         public string Contact { get; set; }
+
+        /// <summary>
+        /// Theme License, like `MIT` etc.
+        /// </summary>
         public string License { get; set; }
+
+        /// <summary>
+        /// Theme Dependencies (DLLs) which the system will check if they exist
+        /// </summary>
         public string Dependencies { get; set; }
+
+        
         public string ThemeSettingsType { get; set; } // added in 2.0.2
         public string ContainerSettingsType { get; set; } // added in 2.0.2
         public string PackageName { get; set; } // added in 2.1.0