Documented the ViewModels

Typically, we don't document view models, since they're meant to be quick and easy to program, and usually the properties are self-explanatory. That said, since the `Ignia.Topics.ViewModels` collection represents a fairly stable and semi-permanent set of view models, which will be used by most implementations of **OnTopic**, it makes sense to provide documentation, not only for any generated reference documentation we may produce in the future, but also to provide an aid in IDEs (e.g., for _Intellisense_, for users of **Visual Studio**).

Author: JeremyCaney

Ignia.Topics.ViewModels/ContentItemTopicViewModel.cs

@@ -19,9 +19,36 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class ContentItemTopicViewModel: ItemTopicViewModel {
 
+    /*==========================================================================================================================
+    | DESCRIPTION
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Gets the description; for Content Items, this is effectively the body.
+    /// </summary>
     public string Description { get; set; } = default!;
+
+    /*==========================================================================================================================
+    | LEARN MORE URL
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Gets an optional URL for additional information that should be linked to.
+    /// </summary>
     public string? LearnMoreUrl { get; set; }
+
+    /*==========================================================================================================================
+    | THUMBNAIL IMAGE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Gets an optional path to a thumbnail image that should accompany the content item.
+    /// </summary>
     public string? ThumbnailImage { get; set; }
+
+    /*==========================================================================================================================
+    | CATEGORY
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Gets the category that the content item should be grouped under.
+    /// </summary>
     public string? Category { get; set; }
 
   } //Class

Ignia.Topics.ViewModels/ContentListTopicViewModel.cs

@@ -19,7 +19,21 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class ContentListTopicViewModel: PageTopicViewModel {
 
+    /*==========================================================================================================================
+    | CONTENT ITEMS
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a list of <see cref="ContentItemTopicViewModel"/>, representing the contents of the <see
+    ///   cref="ContentListTopicViewModel"/>.
+    /// </summary>
     public TopicViewModelCollection<ContentItemTopicViewModel> ContentItems { get; } = new TopicViewModelCollection<ContentItemTopicViewModel>();
+
+    /*==========================================================================================================================
+    | CATEGORIES
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a list of valid categories that each of the <see cref="ContentItems"/> may optionally be associated with.
+    /// </summary>
     public TopicViewModelCollection<TopicViewModel> Categories { get; } = new TopicViewModelCollection<TopicViewModel>();
 
   } //Class

Ignia.Topics.ViewModels/NavigationTopicViewModel.cs

@@ -30,8 +30,29 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public sealed class NavigationTopicViewModel : TopicViewModel, INavigationTopicViewModel<NavigationTopicViewModel> {
 
+    /*==========================================================================================================================
+    | SHORT TITLE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a short title to be used in the navigation, for cases where the normal title is too long.
+    /// </summary>
     public string? ShortTitle { get; set; }
+
+    /*==========================================================================================================================
+    | CHILDREN
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a list of nested <see cref="NavigationTopicViewModel"/> objects, for handling hierarchical navigation.
+    /// </summary>
     public Collection<NavigationTopicViewModel> Children { get; } = new Collection<NavigationTopicViewModel>();
+
+    /*==========================================================================================================================
+    | IS SELECTED?
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Determines whether or not the node represented by this <see cref="NavigationTopicViewModel"/> is currently selected,
+    ///   typically meaning the user is on the page this object is pointing to.
+    /// </summary>
     public bool IsSelected(string uniqueKey) =>
       $"{uniqueKey}:"?.StartsWith($"{UniqueKey}:", StringComparison.InvariantCultureIgnoreCase) ?? false;
 

Ignia.Topics.ViewModels/PageTopicViewModel.cs

@@ -20,20 +20,50 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class PageTopicViewModel: TopicViewModel, IPageTopicViewModel {
 
+    /*==========================================================================================================================
+    | SUBTITLE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides an optional subtitle which will typically be displayed under the title.
+    /// </summary>
     public string? Subtitle { get; set; }
 
+    /*==========================================================================================================================
+    | META TITLE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides an optional title to be used in page's metadata, if it differs from the <see cref="TopicViewModel.Title"/>.
+    /// </summary>
     public string? MetaTitle { get; set; }
 
+    /*==========================================================================================================================
+    | META DESCRIPTION
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? MetaDescription { get; set; }
 
+    /*==========================================================================================================================
+    | META KEYWORDS
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? MetaKeywords { get; set; }
 
     public bool? NoIndex { get; set; }
 
+    /*==========================================================================================================================
+    | SHORT TITLE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a short title to be used in the navigation, for cases where the normal title is too long.
+    /// </summary>
     public string? ShortTitle { get; set; }
 
+    /*==========================================================================================================================
+    | BODY
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides the primary content for the page, which is typically in HTML format.
+    /// </summary>
     public string? Body { get; set; }
 
   } //Class

Ignia.Topics.ViewModels/SectionTopicViewModel.cs

@@ -19,6 +19,12 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class SectionTopicViewModel : TopicViewModel {
 
+    /*==========================================================================================================================
+    | HEADER IMAGE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a header image which may be displayed at the top of a section.
+    /// </summary>
     public string? HeaderImageUrl { get; set; }
 
   } //Class

Ignia.Topics.ViewModels/SlideshowTopicViewModel.cs

@@ -19,6 +19,17 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class SlideshowTopicViewModel: ContentListTopicViewModel {
 
+    /*==========================================================================================================================
+    | TRANSITION EFFECT
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides the transition effect to use when flipping between slides.
+    /// </summary>
+    /// <remarks>
+    ///   The effective values for <see cref="TransitionEffect"/> are dependent on the library used for presenting the
+    ///   slideshow. Typically, they will map to standard HTML5/CSS3 transition effects, but they could differ depending on the
+    ///   implementation.
+    /// </remarks>
     public string? TransitionEffect { get; set; }
 
   } //Class

Ignia.Topics.ViewModels/TopicViewModel.cs

@@ -22,32 +22,69 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class TopicViewModel: ITopicViewModel {
 
+    /*==========================================================================================================================
+    | ID
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public int Id { get; set; }
 
+    /*==========================================================================================================================
+    | KEY
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? Key { get; set; }
 
+    /*==========================================================================================================================
+    | CONTENT TYPE
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? ContentType { get; set; }
 
+    /*==========================================================================================================================
+    | UNIQUE KEY
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? UniqueKey { get; set; }
 
+    /*==========================================================================================================================
+    | WEB PATH
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? WebPath { get; set; }
 
+    /*==========================================================================================================================
+    | VIEW
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? View { get; set; }
 
+    /*==========================================================================================================================
+    | TITLE
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public string? Title { get; set; }
 
+    /*==========================================================================================================================
+    | IS HIDDEN?
+    \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc />
     public bool IsHidden { get; set; }
 
     public DateTime LastModified { get; set; }
 
+    /*==========================================================================================================================
+    | PARENT
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a reference to the parent <see cref="TopicViewModel"/> in the topic hierarchy.
+    /// </summary>
+    /// <remarks>
+    ///   If the current <see cref="TopicViewModel"/> is being mapped as part of another <see cref="TopicViewModel"/>, then the
+    ///   <see cref="Parent"/> property will only be mapped if that relationship includes a <see cref="FollowAttribute"/>
+    ///   with a value including <see cref="Relationships.Parents"/>. If it does, all <see cref="Parent"/> topics will be mapped
+    ///   up to the root of the site. No other relationships on the <see cref="Parent"/> view models will be mapped, even if
+    ///   they are annotated with a <see cref="FollowAttribute"/>.
+    /// </remarks>
     [Follow(Relationships.Parents)]
     public TopicViewModel? Parent { get; set; }
 

Ignia.Topics.ViewModels/VideoTopicViewModel.cs

@@ -19,7 +19,20 @@ namespace Ignia.Topics.ViewModels {
   /// </remarks>
   public class VideoTopicViewModel: PageTopicViewModel {
 
+    /*==========================================================================================================================
+    | VIDEO URL
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a URL reference to a video to display on the page.
+    /// </summary>
     public string? VideoUrl { get; set; }
+
+    /*==========================================================================================================================
+    | POSTER URL
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a URL reference to an image to display prior to playing the video.
+    /// </summary>
     public string? PosterUrl { get; set; }
 
   } //Class