added DefaultDocumentationNestedTypeVisibility parameter to set where…

… nested types are displayed (possible value: Namespace, DeclaringType,Everywhere) (solve #17)
Doraku · May 10, 2020 · 10e5cf1 · 10e5cf1
1 parent 94d80d8
commit 10e5cf1
Show file tree

Hide file tree

Showing 8 changed files with 106 additions and 45 deletions.
diff --git a/source/DefaultDocumentation/DefaultDocumentation.Release.csproj b/source/DefaultDocumentation/DefaultDocumentation.Release.csproj
@@ -7,11 +7,9 @@
   </PropertyGroup>
 
   <PropertyGroup Label="Package">
-    <Version>0.6.2</Version>
+    <Version>0.6.3</Version>
     <PackageReleaseNotes>
-added DefaultDocumentationFileNameMode parameter to change the way documentation pages are named (possible values: FullName, Md5)
-
-fixed invalid char in file name generation
+added DefaultDocumentationNestedTypeVisibility parameter to set where nested types are displayed (possible value: Namespace, DeclaringType,Everywhere)
     </PackageReleaseNotes>
   </PropertyGroup>
 </Project>
diff --git a/source/DefaultDocumentation/DocumentationGenerator.cs b/source/DefaultDocumentation/DocumentationGenerator.cs
@@ -16,14 +16,22 @@ internal sealed class DocumentationGenerator
         private readonly CSharpDecompiler _decompiler;
         private readonly XmlDocumentationProvider _documentationProvider;
         private readonly FileNameMode _fileNameMode;
+        private readonly NestedTypeVisibility _nestedTypeVisibility;
         private readonly Dictionary<string, DocItem> _docItems;
         private readonly Dictionary<string, string> _links;
 
-        public DocumentationGenerator(string assemblyFilePath, string documentationFilePath, string homePageName, FileNameMode fileNameMode, string linksFiles)
+        public DocumentationGenerator(
+            string assemblyFilePath,
+            string documentationFilePath,
+            string homePageName,
+            FileNameMode fileNameMode,
+            NestedTypeVisibility nestedTypeVisibility,
+            string linksFiles)
         {
             _decompiler = new CSharpDecompiler(assemblyFilePath, new DecompilerSettings());
             _documentationProvider = new XmlDocumentationProvider(documentationFilePath);
             _fileNameMode = fileNameMode;
+            _nestedTypeVisibility = nestedTypeVisibility;
 
             _docItems = new Dictionary<string, DocItem>();
             foreach (DocItem item in GetDocItems(homePageName))
@@ -152,7 +160,7 @@ public void WriteDocumentation(string outputFolderPath)
         {
             _docItems.Values.Where(i => i.GeneratePage).AsParallel().ForAll(i =>
             {
-                using DocumentationWriter writer = new DocumentationWriter(_fileNameMode, _docItems, _links, outputFolderPath, i);
+                using DocumentationWriter writer = new DocumentationWriter(_fileNameMode, _nestedTypeVisibility, _docItems, _links, outputFolderPath, i);
 
                 i.WriteDocumentation(writer);
             });

diff --git a/source/DefaultDocumentation/DocumentationWriter.cs b/source/DefaultDocumentation/DocumentationWriter.cs
@@ -24,14 +24,23 @@ internal sealed class DocumentationWriter : IDisposable
         private readonly DocItem _mainItem;
         private readonly string _filePath;
 
-        public DocumentationWriter(FileNameMode fileNameMode, IReadOnlyDictionary<string, DocItem> items, IReadOnlyDictionary<string, string> links, string folderPath, DocItem item)
+        public NestedTypeVisibility NestedTypeVisibility { get; }
+
+        public DocumentationWriter(
+            FileNameMode fileNameMode,
+            NestedTypeVisibility nestedTypeVisibility,
+            IReadOnlyDictionary<string, DocItem> items,
+            IReadOnlyDictionary<string, string> links,
+            string folderPath,
+            DocItem item)
         {
             if (!_builders.TryDequeue(out _builder))
             {
                 _builder = new StringBuilder(1024);
             }
 
             _fileNameMode = fileNameMode;
+            NestedTypeVisibility = nestedTypeVisibility;
             _items = items;
             _links = links;
             _mainItem = item;

diff --git a/source/DefaultDocumentation/Model/NamespaceDocItem.cs b/source/DefaultDocumentation/Model/NamespaceDocItem.cs
@@ -18,11 +18,23 @@ public override void WriteDocumentation(DocumentationWriter writer)
 
             writer.Write("### Remarks", Documentation.GetRemarks(), this);
 
-            writer.WriteChildrenLink<ClassDocItem>("Classes");
-            writer.WriteChildrenLink<StructDocItem>("Structs");
-            writer.WriteChildrenLink<InterfaceDocItem>("Interfaces");
-            writer.WriteChildrenLink<EnumDocItem>("Enums");
-            writer.WriteChildrenLink<DelegateDocItem>("Delegates");
+            if (writer.NestedTypeVisibility == NestedTypeVisibility.Namespace
+                || writer.NestedTypeVisibility == NestedTypeVisibility.Everywhere)
+            {
+                writer.WriteChildrenLink<ClassDocItem>("Classes");
+                writer.WriteChildrenLink<StructDocItem>("Structs");
+                writer.WriteChildrenLink<InterfaceDocItem>("Interfaces");
+                writer.WriteChildrenLink<EnumDocItem>("Enums");
+                writer.WriteChildrenLink<DelegateDocItem>("Delegates");
+            }
+            else
+            {
+                writer.WriteDirectChildrenLink<ClassDocItem>("Classes");
+                writer.WriteDirectChildrenLink<StructDocItem>("Structs");
+                writer.WriteDirectChildrenLink<InterfaceDocItem>("Interfaces");
+                writer.WriteDirectChildrenLink<EnumDocItem>("Enums");
+                writer.WriteDirectChildrenLink<DelegateDocItem>("Delegates");
+            }
         }
     }
 }
diff --git a/source/DefaultDocumentation/Model/TypeDocItem.cs b/source/DefaultDocumentation/Model/TypeDocItem.cs
@@ -94,6 +94,16 @@ public override void WriteDocumentation(DocumentationWriter writer)
             writer.WriteDirectChildrenLink<MethodDocItem>("Methods");
             writer.WriteDirectChildrenLink<EventDocItem>("Events");
             writer.WriteDirectChildrenLink<OperatorDocItem>("Operators");
+
+            if (writer.NestedTypeVisibility == NestedTypeVisibility.DeclaringType
+                || writer.NestedTypeVisibility == NestedTypeVisibility.Everywhere)
+            {
+                writer.WriteDirectChildrenLink<ClassDocItem>("Classes");
+                writer.WriteDirectChildrenLink<StructDocItem>("Structs");
+                writer.WriteDirectChildrenLink<InterfaceDocItem>("Interfaces");
+                writer.WriteDirectChildrenLink<EnumDocItem>("Enums");
+                writer.WriteDirectChildrenLink<DelegateDocItem>("Delegates");
+            }
         }
     }
 }
diff --git a/source/DefaultDocumentation/NestedTypeVisibility.cs b/source/DefaultDocumentation/NestedTypeVisibility.cs
@@ -0,0 +1,9 @@
+namespace DefaultDocumentation
+{
+    public enum NestedTypeVisibility
+    {
+        Namespace,
+        DeclaringType,
+        Everywhere
+    }
+}
diff --git a/source/DefaultDocumentation/Program.cs b/source/DefaultDocumentation/Program.cs
@@ -12,45 +12,58 @@ private static void Main(string[] args)
             DirectoryInfo output = null;
             string home = null;
             FileNameMode fileNameMode = FileNameMode.FullName;
+            NestedTypeVisibility nestedTypeVisibility = NestedTypeVisibility.Namespace;
             string baselink = null;
             FileInfo linksfile = null;
             string externallinks = null;
 
-            foreach (string arg in args)
+            try
             {
-                if (TryGetArgValue(arg, nameof(assembly), out string argValue))
+                foreach (string arg in args)
                 {
-                    assembly = new FileInfo(argValue);
-                }
-                else if (TryGetArgValue(arg, nameof(xml), out argValue))
-                {
-                    xml = new FileInfo(argValue);
-                }
-                else if (TryGetArgValue(arg, nameof(output), out argValue) && !string.IsNullOrWhiteSpace(argValue))
-                {
-                    output = new DirectoryInfo(argValue);
-                }
-                else if (TryGetArgValue(arg, nameof(home), out argValue) && !string.IsNullOrWhiteSpace(argValue))
-                {
-                    home = argValue;
-                }
-                else if (TryGetArgValue(arg, nameof(fileNameMode), out argValue))
-                {
-                    fileNameMode = (FileNameMode)Enum.Parse(typeof(FileNameMode), argValue);
-                }
-                else if (TryGetArgValue(arg, nameof(baselink), out argValue) && !string.IsNullOrWhiteSpace(argValue))
-                {
-                    baselink = argValue;
-                }
-                else if (TryGetArgValue(arg, nameof(linksfile), out argValue) && !string.IsNullOrWhiteSpace(argValue))
-                {
-                    linksfile = new FileInfo(argValue);
-                }
-                else if (TryGetArgValue(arg, nameof(externallinks), out argValue) && !string.IsNullOrWhiteSpace(argValue))
-                {
-                    externallinks = argValue;
+                    if (TryGetArgValue(arg, nameof(assembly), out string argValue))
+                    {
+                        assembly = new FileInfo(argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(xml), out argValue))
+                    {
+                        xml = new FileInfo(argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(output), out argValue) && !string.IsNullOrWhiteSpace(argValue))
+                    {
+                        output = new DirectoryInfo(argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(home), out argValue) && !string.IsNullOrWhiteSpace(argValue))
+                    {
+                        home = argValue;
+                    }
+                    else if (TryGetArgValue(arg, nameof(fileNameMode), out argValue))
+                    {
+                        fileNameMode = (FileNameMode)Enum.Parse(typeof(FileNameMode), argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(nestedTypeVisibility), out argValue))
+                    {
+                        nestedTypeVisibility = (NestedTypeVisibility)Enum.Parse(typeof(NestedTypeVisibility), argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(baselink), out argValue) && !string.IsNullOrWhiteSpace(argValue))
+                    {
+                        baselink = argValue;
+                    }
+                    else if (TryGetArgValue(arg, nameof(linksfile), out argValue) && !string.IsNullOrWhiteSpace(argValue))
+                    {
+                        linksfile = new FileInfo(argValue);
+                    }
+                    else if (TryGetArgValue(arg, nameof(externallinks), out argValue) && !string.IsNullOrWhiteSpace(argValue))
+                    {
+                        externallinks = argValue;
+                    }
                 }
             }
+            catch
+            {
+                PrintHelp();
+                throw;
+            }
 
             if (assembly is null || xml is null)
             {
@@ -82,7 +95,7 @@ private static void Main(string[] args)
                 output.Create();
             }
 
-            DocumentationGenerator generator = new DocumentationGenerator(assembly.FullName, xml.FullName, home, fileNameMode, externallinks);
+            DocumentationGenerator generator = new DocumentationGenerator(assembly.FullName, xml.FullName, home, fileNameMode, nestedTypeVisibility, externallinks);
 
             generator.WriteDocumentation(output.FullName);
 
@@ -116,6 +129,7 @@ void PrintHelp()
                 Console.WriteLine($"\t/{nameof(output)}:{{DefaultDocumentation output folder}}");
                 Console.WriteLine($"\t/{nameof(home)}:{{DefaultDocumentation home page name}}");
                 Console.WriteLine($"\t/{nameof(fileNameMode)}:{{{string.Join(" | ", Enum.GetValues(typeof(FileNameMode)))}}}");
+                Console.WriteLine($"\t/{nameof(nestedTypeVisibility)}:{{{string.Join(" | ", Enum.GetValues(typeof(NestedTypeVisibility)))}}}");
                 Console.WriteLine($"\t/{nameof(baselink)}:{{base link path used if generating a links file}}");
                 Console.WriteLine($"\t/{nameof(linksfile)}:{{links file path}}");
                 Console.WriteLine($"\t/{nameof(externallinks)}:{{links files for element outside of this assembly, separated by '|'}}");

diff --git a/source/DefaultDocumentation/build/DefaultDocumentation.targets b/source/DefaultDocumentation/build/DefaultDocumentation.targets
@@ -9,9 +9,10 @@
       <DocumentationFile Condition="'$(DocumentationFile)' != ''">$([System.IO.Path]::GetFullPath($(DocumentationFile)))</DocumentationFile>
       <DefaultDocumentationFolder Condition="'$(DefaultDocumentationFolder)' != ''">$([System.IO.Path]::GetFullPath($(DefaultDocumentationFolder)))</DefaultDocumentationFolder>
       <DefaultDocumentationFileNameMode Condition="'$(DefaultDocumentationFileNameMode)' == ''">FullName</DefaultDocumentationFileNameMode>
+      <DefaultDocumentationNestedTypeVisibility Condition="'$(DefaultDocumentationNestedTypeVisibility)' == ''">Namespace</DefaultDocumentationNestedTypeVisibility>
       <DefaultDocumentationLinksFile Condition="'$(DefaultDocumentationLinksFile)' != ''">$([System.IO.Path]::GetFullPath($(DefaultDocumentationLinksFile)))</DefaultDocumentationLinksFile>
 
-      <DefaultDocumentationCommand>$(DefaultDocumentationTool) /assembly:"$(TargetPath)" /xml:"$(DocumentationFile)" /output:"$(DefaultDocumentationFolder)" /home:"$(DefaultDocumentationHome)" /fileNameMode:$(DefaultDocumentationFileNameMode)</DefaultDocumentationCommand>
+      <DefaultDocumentationCommand>$(DefaultDocumentationTool) /assembly:"$(TargetPath)" /xml:"$(DocumentationFile)" /output:"$(DefaultDocumentationFolder)" /home:"$(DefaultDocumentationHome)" /fileNameMode:"$(DefaultDocumentationFileNameMode)" /nestedTypeVisibility:"$(DefaultDocumentationNestedTypeVisibility)"</DefaultDocumentationCommand>
       <DefaultDocumentationCommandLinksParameters>/baselink:"$(DefaultDocumentationBaseLink)" /linksfile:"$(DefaultDocumentationLinksFile)"</DefaultDocumentationCommandLinksParameters>
     </PropertyGroup>
     <Exec Command="$(DefaultDocumentationCommand) $(DefaultDocumentationCommandLinksParameters)"/>