Merge pull request #6342 from richlander/mediabrowser-controller-library

MediaBrowser.Controller/Library/ILibraryManager.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CS1591
 
 using System;
 using System.Collections.Generic;
@@ -31,6 +31,29 @@ namespace MediaBrowser.Controller.Library
     /// </summary>
     public interface ILibraryManager
     {
+        /// <summary>
+        /// Occurs when [item added].
+        /// </summary>
+        event EventHandler<ItemChangeEventArgs> ItemAdded;
+
+        /// <summary>
+        /// Occurs when [item updated].
+        /// </summary>
+        event EventHandler<ItemChangeEventArgs> ItemUpdated;
+
+        /// <summary>
+        /// Occurs when [item removed].
+        /// </summary>
+        event EventHandler<ItemChangeEventArgs> ItemRemoved;
+
+        /// <summary>
+        /// Gets the root folder.
+        /// </summary>
+        /// <value>The root folder.</value>
+        AggregateFolder RootFolder { get; }
+
+        bool IsScanRunning { get; }
+
         /// <summary>
         /// Resolves the path.
         /// </summary>
@@ -57,16 +80,10 @@ namespace MediaBrowser.Controller.Library
             LibraryOptions libraryOptions,
             string collectionType = null);
 
-        /// <summary>
-        /// Gets the root folder.
-        /// </summary>
-        /// <value>The root folder.</value>
-        AggregateFolder RootFolder { get; }
-
         /// <summary>
         /// Gets a Person.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The name of the person.</param>
         /// <returns>Task{Person}.</returns>
         Person GetPerson(string name);
 
@@ -81,7 +98,7 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets the artist.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The name of the artist.</param>
         /// <returns>Task{Artist}.</returns>
         MusicArtist GetArtist(string name);
 
@@ -90,21 +107,21 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets a Studio.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The name of the studio.</param>
         /// <returns>Task{Studio}.</returns>
         Studio GetStudio(string name);
 
         /// <summary>
         /// Gets a Genre.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The name of the genre.</param>
         /// <returns>Task{Genre}.</returns>
         Genre GetGenre(string name);
 
         /// <summary>
         /// Gets the genre.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The name of the music genre.</param>
         /// <returns>Task{MusicGenre}.</returns>
         MusicGenre GetMusicGenre(string name);
 
@@ -113,7 +130,7 @@ namespace MediaBrowser.Controller.Library
         /// </summary>
         /// <param name="value">The value.</param>
         /// <returns>Task{Year}.</returns>
-        /// <exception cref="ArgumentOutOfRangeException"></exception>
+        /// <exception cref="ArgumentOutOfRangeException">Throws if year is invalid.</exception>
         Year GetYear(int value);
 
         /// <summary>
@@ -205,16 +222,26 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Creates the item.
         /// </summary>
+        /// <param name="item">Item to create.</param>
+        /// <param name="parent">Parent of new item.</param>
         void CreateItem(BaseItem item, BaseItem parent);
 
         /// <summary>
         /// Creates the items.
         /// </summary>
+        /// <param name="items">Items to create.</param>
+        /// <param name="parent">Parent of new items.</param>
+        /// <param name="cancellationToken">CancellationToken to use for operation.</param>
         void CreateItems(IReadOnlyList<BaseItem> items, BaseItem parent, CancellationToken cancellationToken);
 
         /// <summary>
         /// Updates the item.
         /// </summary>
+        /// <param name="items">Items to update.</param>
+        /// <param name="parent">Parent of updated items.</param>
+        /// <param name="updateReason">Reason for update.</param>
+        /// <param name="cancellationToken">CancellationToken to use for operation.</param>
+        /// <returns>Returns a Task that can be awaited.</returns>
         Task UpdateItemsAsync(IReadOnlyList<BaseItem> items, BaseItem parent, ItemUpdateType updateReason, CancellationToken cancellationToken);
 
         /// <summary>
@@ -224,6 +251,7 @@ namespace MediaBrowser.Controller.Library
         /// <param name="parent">The parent item.</param>
         /// <param name="updateReason">The update reason.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>Returns a Task that can be awaited.</returns>
         Task UpdateItemAsync(BaseItem item, BaseItem parent, ItemUpdateType updateReason, CancellationToken cancellationToken);
 
         /// <summary>
@@ -233,23 +261,6 @@ namespace MediaBrowser.Controller.Library
         /// <returns>BaseItem.</returns>
         BaseItem RetrieveItem(Guid id);
 
-        bool IsScanRunning { get; }
-
-        /// <summary>
-        /// Occurs when [item added].
-        /// </summary>
-        event EventHandler<ItemChangeEventArgs> ItemAdded;
-
-        /// <summary>
-        /// Occurs when [item updated].
-        /// </summary>
-        event EventHandler<ItemChangeEventArgs> ItemUpdated;
-
-        /// <summary>
-        /// Occurs when [item removed].
-        /// </summary>
-        event EventHandler<ItemChangeEventArgs> ItemRemoved;
-
         /// <summary>
         /// Finds the type of the collection.
         /// </summary>
@@ -294,16 +305,25 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Deletes the item.
         /// </summary>
+        /// <param name="item">Item to delete.</param>
+        /// <param name="options">Options to use for deletion.</param>
         void DeleteItem(BaseItem item, DeleteOptions options);
 
         /// <summary>
         /// Deletes the item.
         /// </summary>
+        /// <param name="item">Item to delete.</param>
+        /// <param name="options">Options to use for deletion.</param>
+        /// <param name="notifyParentItem">Notify parent of deletion.</param>
         void DeleteItem(BaseItem item, DeleteOptions options, bool notifyParentItem);
 
         /// <summary>
         /// Deletes the item.
         /// </summary>
+        /// <param name="item">Item to delete.</param>
+        /// <param name="options">Options to use for deletion.</param>
+        /// <param name="parent">Parent of item.</param>
+        /// <param name="notifyParentItem">Notify parent of deletion.</param>
         void DeleteItem(BaseItem item, DeleteOptions options, BaseItem parent, bool notifyParentItem);
 
         /// <summary>
@@ -314,6 +334,7 @@ namespace MediaBrowser.Controller.Library
         /// <param name="parentId">The parent identifier.</param>
         /// <param name="viewType">Type of the view.</param>
         /// <param name="sortName">Name of the sort.</param>
+        /// <returns>The named view.</returns>
         UserView GetNamedView(
             User user,
             string name,
@@ -328,6 +349,7 @@ namespace MediaBrowser.Controller.Library
         /// <param name="name">The name.</param>
         /// <param name="viewType">Type of the view.</param>
         /// <param name="sortName">Name of the sort.</param>
+        /// <returns>The named view.</returns>
         UserView GetNamedView(
             User user,
             string name,
@@ -340,6 +362,7 @@ namespace MediaBrowser.Controller.Library
         /// <param name="name">The name.</param>
         /// <param name="viewType">Type of the view.</param>
         /// <param name="sortName">Name of the sort.</param>
+        /// <returns>The named view.</returns>
         UserView GetNamedView(
             string name,
             string viewType,
@@ -397,6 +420,9 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Fills the missing episode numbers from path.
         /// </summary>
+        /// <param name="episode">Episode to use.</param>
+        /// <param name="forceRefresh">Option to force refresh of episode numbers.</param>
+        /// <returns>True if successful.</returns>
         bool FillMissingEpisodeNumbersFromPath(Episode episode, bool forceRefresh);
 
         /// <summary>
@@ -539,6 +565,9 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets the items.
         /// </summary>
+        /// <param name="query">The query to use.</param>
+        /// <param name="parents">Items to use for query.</param>
+        /// <returns>List of items.</returns>
         List<BaseItem> GetItemList(InternalItemsQuery query, List<BaseItem> parents);
 
         /// <summary>

MediaBrowser.Controller/Library/ILiveStream.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1711, CS1591
 
 using System.Threading;
 using System.Threading.Tasks;

MediaBrowser.Controller/Library/IMediaSourceManager.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CS1591
 
 using System;
 using System.Collections.Generic;
@@ -62,16 +62,32 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets the playack media sources.
         /// </summary>
+        /// <param name="item">Item to use.</param>
+        /// <param name="user">User to use for operation.</param>
+        /// <param name="allowMediaProbe">Option to allow media probe.</param>
+        /// <param name="enablePathSubstitution">Option to enable path substitution.</param>
+        /// <param name="cancellationToken">CancellationToken to use for operation.</param>
+        /// <returns>List of media sources wrapped in an awaitable task.</returns>
         Task<List<MediaSourceInfo>> GetPlaybackMediaSources(BaseItem item, User user, bool allowMediaProbe, bool enablePathSubstitution, CancellationToken cancellationToken);
 
         /// <summary>
         /// Gets the static media sources.
         /// </summary>
+        /// <param name="item">Item to use.</param>
+        /// <param name="enablePathSubstitution">Option to enable path substitution.</param>
+        /// <param name="user">User to use for operation.</param>
+        /// <returns>List of media sources.</returns>
         List<MediaSourceInfo> GetStaticMediaSources(BaseItem item, bool enablePathSubstitution, User user = null);
 
         /// <summary>
         /// Gets the static media source.
         /// </summary>
+        /// <param name="item">Item to use.</param>
+        /// <param name="mediaSourceId">Media source to get.</param>
+        /// <param name="liveStreamId">Live stream to use.</param>
+        /// <param name="enablePathSubstitution">Option to enable path substitution.</param>
+        /// <param name="cancellationToken">CancellationToken to use for operation.</param>
+        /// <returns>The static media source wrapped in an awaitable task.</returns>
         Task<MediaSourceInfo> GetMediaSource(BaseItem item, string mediaSourceId, string liveStreamId, bool enablePathSubstitution, CancellationToken cancellationToken);
 
         /// <summary>

MediaBrowser.Controller/Library/IMediaSourceProvider.cs

@@ -1,4 +1,4 @@
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CS1591
 
 using System.Collections.Generic;
 using System.Threading;
@@ -21,6 +21,10 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Opens the media source.
         /// </summary>
+        /// <param name="openToken">Token to use.</param>
+        /// <param name="currentLiveStreams">List of live streams.</param>
+        /// <param name="cancellationToken">CancellationToken to use for operation.</param>
+        /// <returns>The media source wrapped as an awaitable task.</returns>
         Task<ILiveStream> OpenMediaSource(string openToken, List<ILiveStream> currentLiveStreams, CancellationToken cancellationToken);
     }
 }

MediaBrowser.Controller/Library/IMetadataSaver.cs

@@ -29,7 +29,6 @@ namespace MediaBrowser.Controller.Library
         /// </summary>
         /// <param name="item">The item.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        /// <returns>Task.</returns>
         void Save(BaseItem item, CancellationToken cancellationToken);
     }
 }

MediaBrowser.Controller/Library/IMusicManager.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CS1591
 
 using System.Collections.Generic;
 using Jellyfin.Data.Entities;
@@ -15,16 +15,28 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets the instant mix from song.
         /// </summary>
+        /// <param name="item">The item to use.</param>
+        /// <param name="user">The user to use.</param>
+        /// <param name="dtoOptions">The options to use.</param>
+        /// <returns>List of items.</returns>
         List<BaseItem> GetInstantMixFromItem(BaseItem item, User user, DtoOptions dtoOptions);
 
         /// <summary>
         /// Gets the instant mix from artist.
         /// </summary>
+        /// <param name="artist">The artist to use.</param>
+        /// <param name="user">The user to use.</param>
+        /// <param name="dtoOptions">The options to use.</param>
+        /// <returns>List of items.</returns>
         List<BaseItem> GetInstantMixFromArtist(MusicArtist artist, User user, DtoOptions dtoOptions);
 
         /// <summary>
         /// Gets the instant mix from genre.
         /// </summary>
+        /// <param name="genres">The genres to use.</param>
+        /// <param name="user">The user to use.</param>
+        /// <param name="dtoOptions">The options to use.</param>
+        /// <returns>List of items.</returns>
         List<BaseItem> GetInstantMixFromGenres(IEnumerable<string> genres, User user, DtoOptions dtoOptions);
     }
 }

MediaBrowser.Controller/Library/IUserDataManager.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CA1707, CS1591
 
 using System;
 using System.Collections.Generic;
@@ -42,6 +42,9 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Gets the user data dto.
         /// </summary>
+        /// <param name="item">Item to use.</param>
+        /// <param name="user">User to use.</param>
+        /// <returns>User data dto.</returns>
         UserItemDataDto GetUserDataDto(BaseItem item, User user);
 
         UserItemDataDto GetUserDataDto(BaseItem item, BaseItemDto itemDto, User user, DtoOptions dto_options);
@@ -64,6 +67,10 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Updates playstate for an item and returns true or false indicating if it was played to completion.
         /// </summary>
+        /// <param name="item">Item to update.</param>
+        /// <param name="data">Data to update.</param>
+        /// <param name="positionTicks">New playstate.</param>
+        /// <returns>True if playstate was updated.</returns>
         bool UpdatePlayState(BaseItem item, UserItemData data, long? positionTicks);
     }
 }

MediaBrowser.Controller/Library/IUserManager.cs

@@ -38,6 +38,7 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Initializes the user manager and ensures that a user exists.
         /// </summary>
+        /// <returns>Awaitable task.</returns>
         Task InitializeAsync();
 
         /// <summary>
@@ -109,17 +110,22 @@ namespace MediaBrowser.Controller.Library
         /// Resets the easy password.
         /// </summary>
         /// <param name="user">The user.</param>
-        /// <returns>Task.</returns>
         void ResetEasyPassword(User user);
 
         /// <summary>
         /// Changes the password.
         /// </summary>
+        /// <param name="user">The user.</param>
+        /// <param name="newPassword">New password to use.</param>
+        /// <returns>Awaitable task.</returns>
         Task ChangePassword(User user, string newPassword);
 
         /// <summary>
         /// Changes the easy password.
         /// </summary>
+        /// <param name="user">The user.</param>
+        /// <param name="newPassword">New password to use.</param>
+        /// <param name="newPasswordSha1">Hash of new password.</param>
         void ChangeEasyPassword(User user, string newPassword, string newPasswordSha1);
 
         /// <summary>
@@ -133,6 +139,12 @@ namespace MediaBrowser.Controller.Library
         /// <summary>
         /// Authenticates the user.
         /// </summary>
+        /// <param name="username">The user.</param>
+        /// <param name="password">The password to use.</param>
+        /// <param name="passwordSha1">Hash of password.</param>
+        /// <param name="remoteEndPoint">Remove endpoint to use.</param>
+        /// <param name="isUserSession">Specifies if a user session.</param>
+        /// <returns>User wrapped in awaitable task.</returns>
         Task<User> AuthenticateUser(string username, string password, string passwordSha1, string remoteEndPoint, bool isUserSession);
 
         /// <summary>

MediaBrowser.Controller/Library/IUserViewManager.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CS1591
 
 using System;
 using System.Collections.Generic;
@@ -13,10 +13,29 @@ namespace MediaBrowser.Controller.Library
 {
     public interface IUserViewManager
     {
+        /// <summary>
+        /// Gets user views.
+        /// </summary>
+        /// <param name="query">Query to use.</param>
+        /// <returns>Set of folders.</returns>
         Folder[] GetUserViews(UserViewQuery query);
 
+        /// <summary>
+        /// Gets user sub views.
+        /// </summary>
+        /// <param name="parentId">Parent to use.</param>
+        /// <param name="type">Type to use.</param>
+        /// <param name="localizationKey">Localization key to use.</param>
+        /// <param name="sortName">Sort to use.</param>
+        /// <returns>User view.</returns>
         UserView GetUserSubView(Guid parentId, string type, string localizationKey, string sortName);
 
+        /// <summary>
+        /// Gets latest items.
+        /// </summary>
+        /// <param name="request">Query to use.</param>
+        /// <param name="options">Options to use.</param>
+        /// <returns>Set of items.</returns>
         List<Tuple<BaseItem, List<BaseItem>>> GetLatestItems(LatestItemsQuery request, DtoOptions options);
     }
 }

MediaBrowser.Controller/Library/ItemChangeEventArgs.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1711, CS1591
 
 using MediaBrowser.Controller.Entities;
 

MediaBrowser.Controller/Library/ItemResolveArgs.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1721, CA1819, CS1591
 
 using System;
 using System.Collections.Generic;
@@ -109,6 +109,21 @@ namespace MediaBrowser.Controller.Library
         /// <value>The additional locations.</value>
         private List<string> AdditionalLocations { get; set; }
 
+        /// <summary>
+        /// Gets the physical locations.
+        /// </summary>
+        /// <value>The physical locations.</value>
+        public string[] PhysicalLocations
+        {
+            get
+            {
+                var paths = string.IsNullOrEmpty(Path) ? Array.Empty<string>() : new[] { Path };
+                return AdditionalLocations == null ? paths : paths.Concat(AdditionalLocations).ToArray();
+            }
+        }
+
+        public string CollectionType { get; set; }
+
         public bool HasParent<T>()
             where T : Folder
         {
@@ -138,6 +153,16 @@ namespace MediaBrowser.Controller.Library
             return false;
         }
 
+        /// <summary>
+        /// Determines whether the specified <see cref="object" /> is equal to this instance.
+        /// </summary>
+        /// <param name="obj">The object to compare with the current object.</param>
+        /// <returns><c>true</c> if the specified <see cref="object" /> is equal to this instance; otherwise, <c>false</c>.</returns>
+        public override bool Equals(object obj)
+        {
+            return Equals(obj as ItemResolveArgs);
+        }
+
         /// <summary>
         /// Adds the additional location.
         /// </summary>
@@ -156,19 +181,6 @@ namespace MediaBrowser.Controller.Library
 
         // REVIEW: @bond
 
-        /// <summary>
-        /// Gets the physical locations.
-        /// </summary>
-        /// <value>The physical locations.</value>
-        public string[] PhysicalLocations
-        {
-            get
-            {
-                var paths = string.IsNullOrEmpty(Path) ? Array.Empty<string>() : new[] { Path };
-                return AdditionalLocations == null ? paths : paths.Concat(AdditionalLocations).ToArray();
-            }
-        }
-
         /// <summary>
         /// Gets the name of the file system entry by.
         /// </summary>
@@ -190,7 +202,7 @@ namespace MediaBrowser.Controller.Library
         /// </summary>
         /// <param name="path">The path.</param>
         /// <returns>FileSystemInfo.</returns>
-        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="ArgumentNullException">Throws if path is invalid.</exception>
         public FileSystemMetadata GetFileSystemEntryByPath(string path)
         {
             if (string.IsNullOrEmpty(path))
@@ -224,18 +236,6 @@ namespace MediaBrowser.Controller.Library
             return CollectionType;
         }
 
-        public string CollectionType { get; set; }
-
-        /// <summary>
-        /// Determines whether the specified <see cref="object" /> is equal to this instance.
-        /// </summary>
-        /// <param name="obj">The object to compare with the current object.</param>
-        /// <returns><c>true</c> if the specified <see cref="object" /> is equal to this instance; otherwise, <c>false</c>.</returns>
-        public override bool Equals(object obj)
-        {
-            return Equals(obj as ItemResolveArgs);
-        }
-
         /// <summary>
         /// Returns a hash code for this instance.
         /// </summary>

MediaBrowser.Controller/Library/PlaybackProgressEventArgs.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CA2227, CS1591
 
 using System;
 using System.Collections.Generic;

MediaBrowser.Controller/Library/UserDataSaveEventArgs.cs

@@ -1,6 +1,6 @@
 #nullable disable
 
-#pragma warning disable CS1591
+#pragma warning disable CA1002, CA2227, CS1591
 
 using System;
 using System.Collections.Generic;