From 158eff62d75db2d5e6e6f09fbe6e03eac607fc56 Mon Sep 17 00:00:00 2001 From: Stepan Date: Tue, 10 Nov 2020 19:23:10 +0100 Subject: [PATCH] Xml-doc part2 --- Emby.Naming/Common/MediaType.cs | 3 + Emby.Naming/Common/NamingOptions.cs | 87 +++++++++++++++++++ Emby.Naming/Subtitles/SubtitleInfo.cs | 9 ++ Emby.Naming/Subtitles/SubtitleParser.cs | 14 ++- Emby.Naming/TV/EpisodeResolver.cs | 17 ++++ Emby.Naming/TV/SeasonPathParser.cs | 10 +++ Emby.Naming/TV/SeasonPathParserResult.cs | 7 ++ Emby.Naming/Video/ExtraResolver.cs | 12 +++ Emby.Naming/Video/ExtraResult.cs | 3 + Emby.Naming/Video/ExtraRule.cs | 7 ++ Emby.Naming/Video/FileStack.cs | 21 +++++ Emby.Naming/Video/FlagParser.cs | 18 ++++ Emby.Naming/Video/Format3DParser.cs | 12 +++ Emby.Naming/Video/Format3DResult.cs | 6 ++ Emby.Naming/Video/Format3DRule.cs | 8 ++ Emby.Naming/Video/StackResolver.cs | 27 ++++++ Emby.Naming/Video/StubResolver.cs | 10 +++ Emby.Naming/Video/StubTypeRule.cs | 8 ++ Emby.Naming/Video/VideoListResolver.cs | 13 +++ Emby.Naming/Video/VideoResolver.cs | 29 +++++++ .../Subtitles/SubtitleParserTests.cs | 7 +- 21 files changed, 321 insertions(+), 7 deletions(-) diff --git a/Emby.Naming/Common/MediaType.cs b/Emby.Naming/Common/MediaType.cs index 1231b18871..dc9784c6da 100644 --- a/Emby.Naming/Common/MediaType.cs +++ b/Emby.Naming/Common/MediaType.cs @@ -1,5 +1,8 @@ namespace Emby.Naming.Common { + /// + /// Type of audiovisual media. + /// public enum MediaType { /// diff --git a/Emby.Naming/Common/NamingOptions.cs b/Emby.Naming/Common/NamingOptions.cs index 0f02c03cbb..035d1b2280 100644 --- a/Emby.Naming/Common/NamingOptions.cs +++ b/Emby.Naming/Common/NamingOptions.cs @@ -8,8 +8,14 @@ using MediaBrowser.Model.Entities; namespace Emby.Naming.Common { + /// + /// Big ugly class containing lot of different naming options that should be split and injected instead of passes everywhere. + /// public class NamingOptions { + /// + /// Initializes a new instance of the class. + /// public NamingOptions() { VideoFileExtensions = new[] @@ -644,58 +650,139 @@ namespace Emby.Naming.Common Compile(); } + /// + /// Gets or sets list of audio file extensions. + /// public string[] AudioFileExtensions { get; set; } + /// + /// Gets or sets list of album stacking prefixes. + /// public string[] AlbumStackingPrefixes { get; set; } + /// + /// Gets or sets list of subtitle file extensions. + /// public string[] SubtitleFileExtensions { get; set; } + /// + /// Gets or sets list of subtitles flag delimiters. + /// public char[] SubtitleFlagDelimiters { get; set; } + /// + /// Gets or sets list of subtitle forced flags. + /// public string[] SubtitleForcedFlags { get; set; } + /// + /// Gets or sets list of subtitle default flags. + /// public string[] SubtitleDefaultFlags { get; set; } + /// + /// Gets or sets list of episode regular expressions. + /// public EpisodeExpression[] EpisodeExpressions { get; set; } + /// + /// Gets or sets list of raw episode without season regular expressions strings. + /// public string[] EpisodeWithoutSeasonExpressions { get; set; } + /// + /// Gets or sets list of raw multi-part episodes regular expressions strings. + /// public string[] EpisodeMultiPartExpressions { get; set; } + /// + /// Gets or sets list of video file extensions. + /// public string[] VideoFileExtensions { get; set; } + /// + /// Gets or sets list of video stub file extensions. + /// public string[] StubFileExtensions { get; set; } + /// + /// Gets or sets list of raw audiobook parts regular expressions strings. + /// public string[] AudioBookPartsExpressions { get; set; } + /// + /// Gets or sets list of raw audiobook names regular expressions strings. + /// public string[] AudioBookNamesExpressions { get; set; } + /// + /// Gets or sets list of stub type rules. + /// public StubTypeRule[] StubTypes { get; set; } + /// + /// Gets or sets list of video flag delimiters. + /// public char[] VideoFlagDelimiters { get; set; } + /// + /// Gets or sets list of 3D Format rules. + /// public Format3DRule[] Format3DRules { get; set; } + /// + /// Gets or sets list of raw video file-stacking expressions strings. + /// public string[] VideoFileStackingExpressions { get; set; } + /// + /// Gets or sets list of raw clean DateTimes regular expressions strings. + /// public string[] CleanDateTimes { get; set; } + /// + /// Gets or sets list of raw clean strings regular expressions strings. + /// public string[] CleanStrings { get; set; } + /// + /// Gets or sets list of multi-episode regular expressions. + /// public EpisodeExpression[] MultipleEpisodeExpressions { get; set; } + /// + /// Gets or sets list of extra rules for videos. + /// public ExtraRule[] VideoExtraRules { get; set; } + /// + /// Gets list of video file-stack regular expressions. + /// public Regex[] VideoFileStackingRegexes { get; private set; } = Array.Empty(); + /// + /// Gets list of clean datetime regular expressions. + /// public Regex[] CleanDateTimeRegexes { get; private set; } = Array.Empty(); + /// + /// Gets list of clean string regular expressions. + /// public Regex[] CleanStringRegexes { get; private set; } = Array.Empty(); + /// + /// Gets list of episode without season regular expressions. + /// public Regex[] EpisodeWithoutSeasonRegexes { get; private set; } = Array.Empty(); + /// + /// Gets list of multi-part episode regular expressions. + /// public Regex[] EpisodeMultiPartRegexes { get; private set; } = Array.Empty(); + /// + /// Compiles raw regex strings into regexes. + /// public void Compile() { VideoFileStackingRegexes = VideoFileStackingExpressions.Select(Compile).ToArray(); diff --git a/Emby.Naming/Subtitles/SubtitleInfo.cs b/Emby.Naming/Subtitles/SubtitleInfo.cs index 62cc3ead17..1fb2e0dc89 100644 --- a/Emby.Naming/Subtitles/SubtitleInfo.cs +++ b/Emby.Naming/Subtitles/SubtitleInfo.cs @@ -1,7 +1,16 @@ namespace Emby.Naming.Subtitles { + /// + /// Class holding information about subtitle. + /// public class SubtitleInfo { + /// + /// Initializes a new instance of the class. + /// + /// Path to file. + /// Is subtitle default. + /// Is subtitle forced. public SubtitleInfo(string path, bool isDefault, bool isForced) { Path = path; diff --git a/Emby.Naming/Subtitles/SubtitleParser.cs b/Emby.Naming/Subtitles/SubtitleParser.cs index 476a83cf35..e872452519 100644 --- a/Emby.Naming/Subtitles/SubtitleParser.cs +++ b/Emby.Naming/Subtitles/SubtitleParser.cs @@ -5,20 +5,32 @@ using Emby.Naming.Common; namespace Emby.Naming.Subtitles { + /// + /// Subtitle Parser class. + /// public class SubtitleParser { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing SubtitleFileExtensions, SubtitleDefaultFlags, SubtitleForcedFlags and SubtitleFlagDelimiters. public SubtitleParser(NamingOptions options) { _options = options; } + /// + /// Parse file to determine if is subtitle and . + /// + /// Path to file. + /// Returns null or object if parsing is successful. public SubtitleInfo? ParseFile(string path) { if (path.Length == 0) { - throw new ArgumentException("File path can't be empty.", nameof(path)); + return null; } var extension = Path.GetExtension(path); diff --git a/Emby.Naming/TV/EpisodeResolver.cs b/Emby.Naming/TV/EpisodeResolver.cs index 26dd6915b9..f7df587864 100644 --- a/Emby.Naming/TV/EpisodeResolver.cs +++ b/Emby.Naming/TV/EpisodeResolver.cs @@ -6,15 +6,32 @@ using Emby.Naming.Video; namespace Emby.Naming.TV { + /// + /// Used to resolve information about episode from path. + /// public class EpisodeResolver { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoFileExtensions and passed to , , and . public EpisodeResolver(NamingOptions options) { _options = options; } + /// + /// Resolve information about episode from path. + /// + /// Path. + /// Is path for a directory or file. + /// Do we want to use IsNamed expressions. + /// Do we want to use Optimistic expressions. + /// Do we want to use expressions supporting absolute episode numbers. + /// Should we attempt to retrieve extended information. + /// Returns null or object if successful. public EpisodeInfo? Resolve( string path, bool isDirectory, diff --git a/Emby.Naming/TV/SeasonPathParser.cs b/Emby.Naming/TV/SeasonPathParser.cs index cf99097bc4..d11c7c99e8 100644 --- a/Emby.Naming/TV/SeasonPathParser.cs +++ b/Emby.Naming/TV/SeasonPathParser.cs @@ -4,6 +4,9 @@ using System.IO; namespace Emby.Naming.TV { + /// + /// Class to parse season paths. + /// public static class SeasonPathParser { /// @@ -21,6 +24,13 @@ namespace Emby.Naming.TV "stagione" }; + /// + /// Attempts to parse season number from path. + /// + /// Path to season. + /// Support special aliases when parsing. + /// Support numeric season folders when parsing. + /// Returns object. public static SeasonPathParserResult Parse(string path, bool supportSpecialAliases, bool supportNumericSeasonFolders) { var result = new SeasonPathParserResult(); diff --git a/Emby.Naming/TV/SeasonPathParserResult.cs b/Emby.Naming/TV/SeasonPathParserResult.cs index f52f941a7c..b4b6f236a7 100644 --- a/Emby.Naming/TV/SeasonPathParserResult.cs +++ b/Emby.Naming/TV/SeasonPathParserResult.cs @@ -1,5 +1,8 @@ namespace Emby.Naming.TV { + /// + /// Data object to pass result of . + /// public class SeasonPathParserResult { /// @@ -14,6 +17,10 @@ namespace Emby.Naming.TV /// true if success; otherwise, false. public bool Success { get; set; } + /// + /// Gets or sets a value indicating whether "Is season folder". + /// Seems redundant and barely used. + /// public bool IsSeasonFolder { get; set; } } } diff --git a/Emby.Naming/Video/ExtraResolver.cs b/Emby.Naming/Video/ExtraResolver.cs index 98ea342acc..dd934d91b0 100644 --- a/Emby.Naming/Video/ExtraResolver.cs +++ b/Emby.Naming/Video/ExtraResolver.cs @@ -6,15 +6,27 @@ using Emby.Naming.Common; namespace Emby.Naming.Video { + /// + /// Resolve if file is extra for video. + /// public class ExtraResolver { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoExtraRules and passed to and . public ExtraResolver(NamingOptions options) { _options = options; } + /// + /// Attempts to resolve if file is extra. + /// + /// Path to file. + /// Returns object. public ExtraResult GetExtraInfo(string path) { return _options.VideoExtraRules diff --git a/Emby.Naming/Video/ExtraResult.cs b/Emby.Naming/Video/ExtraResult.cs index f3b8d2a2fc..243fc2b415 100644 --- a/Emby.Naming/Video/ExtraResult.cs +++ b/Emby.Naming/Video/ExtraResult.cs @@ -2,6 +2,9 @@ using MediaBrowser.Model.Entities; namespace Emby.Naming.Video { + /// + /// Holder object for passing results from ExtraResolver. + /// public class ExtraResult { /// diff --git a/Emby.Naming/Video/ExtraRule.cs b/Emby.Naming/Video/ExtraRule.cs index a93474bc69..e267ac55fc 100644 --- a/Emby.Naming/Video/ExtraRule.cs +++ b/Emby.Naming/Video/ExtraRule.cs @@ -8,6 +8,13 @@ namespace Emby.Naming.Video /// public class ExtraRule { + /// + /// Initializes a new instance of the class. + /// + /// Type of extra. + /// Type of rule. + /// Token. + /// Media type. public ExtraRule(ExtraType extraType, ExtraRuleType ruleType, string token, MediaType mediaType) { Token = token; diff --git a/Emby.Naming/Video/FileStack.cs b/Emby.Naming/Video/FileStack.cs index 75620e9610..6519db57c3 100644 --- a/Emby.Naming/Video/FileStack.cs +++ b/Emby.Naming/Video/FileStack.cs @@ -4,19 +4,40 @@ using System.Linq; namespace Emby.Naming.Video { + /// + /// Object holding list of files paths with additional information. + /// public class FileStack { + /// + /// Initializes a new instance of the class. + /// public FileStack() { Files = new List(); } + /// + /// Gets or sets name of file stack. + /// public string Name { get; set; } = string.Empty; + /// + /// Gets or sets list of paths in stack. + /// public List Files { get; set; } + /// + /// Gets or sets a value indicating whether stack is directory stack. + /// public bool IsDirectoryStack { get; set; } + /// + /// Helper function to determine if path is in the stack. + /// + /// Path of desired file. + /// Requested type of stack. + /// True if file is in the stack. public bool ContainsFile(string file, bool isDirectory) { if (IsDirectoryStack == isDirectory) diff --git a/Emby.Naming/Video/FlagParser.cs b/Emby.Naming/Video/FlagParser.cs index cd15b4666f..439de18138 100644 --- a/Emby.Naming/Video/FlagParser.cs +++ b/Emby.Naming/Video/FlagParser.cs @@ -4,20 +4,38 @@ using Emby.Naming.Common; namespace Emby.Naming.Video { + /// + /// Parses list of flags from filename based on delimiters. + /// public class FlagParser { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoFlagDelimiters. public FlagParser(NamingOptions options) { _options = options; } + /// + /// Calls GetFlags function with _options.VideoFlagDelimiters parameter. + /// + /// Path to file. + /// List of found flags. public string[] GetFlags(string path) { return GetFlags(path, _options.VideoFlagDelimiters); } + /// + /// Parses flags from filename based on delimiters. + /// + /// Path to file. + /// Delimiters used to extract flags. + /// List of found flags. public string[] GetFlags(string path, char[] delimiters) { if (string.IsNullOrEmpty(path)) diff --git a/Emby.Naming/Video/Format3DParser.cs b/Emby.Naming/Video/Format3DParser.cs index 73ad36af46..4fd5d78ba7 100644 --- a/Emby.Naming/Video/Format3DParser.cs +++ b/Emby.Naming/Video/Format3DParser.cs @@ -4,15 +4,27 @@ using Emby.Naming.Common; namespace Emby.Naming.Video { + /// + /// Parste 3D format related flags. + /// public class Format3DParser { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoFlagDelimiters and passes options to . public Format3DParser(NamingOptions options) { _options = options; } + /// + /// Parse 3D format related flags. + /// + /// Path to file. + /// Returns object. public Format3DResult Parse(string path) { int oldLen = _options.VideoFlagDelimiters.Length; diff --git a/Emby.Naming/Video/Format3DResult.cs b/Emby.Naming/Video/Format3DResult.cs index 539060c982..ac935f2030 100644 --- a/Emby.Naming/Video/Format3DResult.cs +++ b/Emby.Naming/Video/Format3DResult.cs @@ -2,8 +2,14 @@ using System.Collections.Generic; namespace Emby.Naming.Video { + /// + /// Helper object to return data from . + /// public class Format3DResult { + /// + /// Initializes a new instance of the class. + /// public Format3DResult() { Tokens = new List(); diff --git a/Emby.Naming/Video/Format3DRule.cs b/Emby.Naming/Video/Format3DRule.cs index bee5c109e1..e562691df9 100644 --- a/Emby.Naming/Video/Format3DRule.cs +++ b/Emby.Naming/Video/Format3DRule.cs @@ -1,7 +1,15 @@ namespace Emby.Naming.Video { + /// + /// Data holder class for 3D format rule. + /// public class Format3DRule { + /// + /// Initializes a new instance of the class. + /// + /// Token. + /// Token present before current token. public Format3DRule(string token, string? precedingToken = null) { Token = token; diff --git a/Emby.Naming/Video/StackResolver.cs b/Emby.Naming/Video/StackResolver.cs index d6de468cc9..550c429614 100644 --- a/Emby.Naming/Video/StackResolver.cs +++ b/Emby.Naming/Video/StackResolver.cs @@ -9,25 +9,47 @@ using MediaBrowser.Model.IO; namespace Emby.Naming.Video { + /// + /// Resolve from list of paths. + /// public class StackResolver { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoFileStackingRegexes and passes options to . public StackResolver(NamingOptions options) { _options = options; } + /// + /// Resolves only directories from paths. + /// + /// List of paths. + /// Enumerable of directories. public IEnumerable ResolveDirectories(IEnumerable files) { return Resolve(files.Select(i => new FileSystemMetadata { FullName = i, IsDirectory = true })); } + /// + /// Resolves only files from paths. + /// + /// List of paths. + /// Enumerable of files. public IEnumerable ResolveFiles(IEnumerable files) { return Resolve(files.Select(i => new FileSystemMetadata { FullName = i, IsDirectory = false })); } + /// + /// Resolves audiobooks from paths. + /// + /// List of paths. + /// Enumerable of directories. public IEnumerable ResolveAudioBooks(IEnumerable files) { var groupedDirectoryFiles = files.GroupBy(file => Path.GetDirectoryName(file.Path)); @@ -56,6 +78,11 @@ namespace Emby.Naming.Video } } + /// + /// Resolves videos from paths. + /// + /// List of paths. + /// Enumerable of videos. public IEnumerable Resolve(IEnumerable files) { var resolver = new VideoResolver(_options); diff --git a/Emby.Naming/Video/StubResolver.cs b/Emby.Naming/Video/StubResolver.cs index 6241a46b03..079987fe8a 100644 --- a/Emby.Naming/Video/StubResolver.cs +++ b/Emby.Naming/Video/StubResolver.cs @@ -5,8 +5,18 @@ using Emby.Naming.Common; namespace Emby.Naming.Video { + /// + /// Resolve if file is stub (.disc). + /// public static class StubResolver { + /// + /// Tries to resolve if file is stub (.disc). + /// + /// Path to file. + /// NamingOptions containing StubFileExtensions and StubTypes. + /// Stub type. + /// True if file is a stub. public static bool TryResolveFile(string path, NamingOptions options, out string? stubType) { stubType = default; diff --git a/Emby.Naming/Video/StubTypeRule.cs b/Emby.Naming/Video/StubTypeRule.cs index df2d3c7d22..dfb3ac013d 100644 --- a/Emby.Naming/Video/StubTypeRule.cs +++ b/Emby.Naming/Video/StubTypeRule.cs @@ -1,7 +1,15 @@ namespace Emby.Naming.Video { + /// + /// Data class holding information about Stub type rule. + /// public class StubTypeRule { + /// + /// Initializes a new instance of the class. + /// + /// Token. + /// Stub type. public StubTypeRule(string token, string stubType) { Token = token; diff --git a/Emby.Naming/Video/VideoListResolver.cs b/Emby.Naming/Video/VideoListResolver.cs index dda3225217..ee0e4d4659 100644 --- a/Emby.Naming/Video/VideoListResolver.cs +++ b/Emby.Naming/Video/VideoListResolver.cs @@ -9,15 +9,28 @@ using MediaBrowser.Model.IO; namespace Emby.Naming.Video { + /// + /// Resolves alternative versions and extras from list of video files. + /// public class VideoListResolver { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing CleanStringRegexes and VideoFlagDelimiters and passes options to and . public VideoListResolver(NamingOptions options) { _options = options; } + /// + /// Resolves alternative versions and extras from list of video files. + /// + /// List of related video files. + /// Indication we should consider multi-versions of content. + /// Returns enumerable of which groups files togeather when related. public IEnumerable Resolve(List files, bool supportMultiVersion = true) { var videoResolver = new VideoResolver(_options); diff --git a/Emby.Naming/Video/VideoResolver.cs b/Emby.Naming/Video/VideoResolver.cs index 31b47cdf15..d7165d8d7f 100644 --- a/Emby.Naming/Video/VideoResolver.cs +++ b/Emby.Naming/Video/VideoResolver.cs @@ -5,10 +5,18 @@ using Emby.Naming.Common; namespace Emby.Naming.Video { + /// + /// Resolves from file path. + /// public class VideoResolver { private readonly NamingOptions _options; + /// + /// Initializes a new instance of the class. + /// + /// object containing VideoFileExtensions, StubFileExtensions, CleanStringRegexes and CleanDateTimeRegexes + /// and passes options in , , and . public VideoResolver(NamingOptions options) { _options = options; @@ -110,23 +118,44 @@ namespace Emby.Naming.Video extraRule: extraResult.Rule); } + /// + /// Determines if path is video file based on extension. + /// + /// Path to file. + /// True if is video file. public bool IsVideoFile(string path) { var extension = Path.GetExtension(path) ?? string.Empty; return _options.VideoFileExtensions.Contains(extension, StringComparer.OrdinalIgnoreCase); } + /// + /// Determines if path is video file stub based on extension. + /// + /// Path to file. + /// True if is video file stub. public bool IsStubFile(string path) { var extension = Path.GetExtension(path) ?? string.Empty; return _options.StubFileExtensions.Contains(extension, StringComparer.OrdinalIgnoreCase); } + /// + /// Tries to clean name of clutter. + /// + /// Raw name. + /// Clean name. + /// True if cleaning of name was successful. public bool TryCleanString(string name, out ReadOnlySpan newName) { return CleanStringParser.TryClean(name, _options.CleanStringRegexes, out newName); } + /// + /// Tries to get name and year from raw name. + /// + /// Raw name. + /// Returns with name and optional year. public CleanDateTimeResult CleanDateTime(string name) { return CleanDateTimeParser.Clean(name, _options.CleanDateTimeRegexes); diff --git a/tests/Jellyfin.Naming.Tests/Subtitles/SubtitleParserTests.cs b/tests/Jellyfin.Naming.Tests/Subtitles/SubtitleParserTests.cs index 5152098908..f3abacb4f9 100644 --- a/tests/Jellyfin.Naming.Tests/Subtitles/SubtitleParserTests.cs +++ b/tests/Jellyfin.Naming.Tests/Subtitles/SubtitleParserTests.cs @@ -31,17 +31,12 @@ namespace Jellyfin.Naming.Tests.Subtitles [Theory] [InlineData("The Skin I Live In (2011).mp4")] + [InlineData("")] public void SubtitleParser_InvalidFileName_ReturnsNull(string input) { var parser = new SubtitleParser(_namingOptions); Assert.Null(parser.ParseFile(input)); } - - [Fact] - public void SubtitleParser_EmptyFileName_ThrowsArgumentException() - { - Assert.Throws(() => new SubtitleParser(_namingOptions).ParseFile(string.Empty)); - } } }