Migrated Documentation library from NetFlow.DocumentationHelper.Library

2026-01-28 13:15:44 +00:00
parent ab700413fb
commit d20a80c44c
152 changed files with 714 additions and 94 deletions
@@ -0,0 +1,193 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using System.Xml;
+using Microsoft.Extensions.DependencyModel;
+using OmegaLeo.HelperLib.Shared.Attributes;
+using OmegaLeo.HelperLib.Documentation.Models;
+
+namespace OmegaLeo.HelperLib.Documentation.Helpers
+{
+
+    [Changelog("1.2.0", "Migrated DocumentationHelper library from NetFlow.DocumentationHelper.Library to it's own package in OmegaLeo.HelperLib")]
+    public static class DocumentationHelperTool
+    {
+        [Documentation("GenerateDocumentation (bool generateForPackageAssembly)",
+            @"Generates a List of objects of type DocumentationStructure that contain the following fields:  
+**AssemblyName**: Name of the main Assembly, used to identify the root namespace  
+**ClassName**: Name of the class, used to identify the upper level object  
+**Title**: Title what we're generating documentation for  
+**Description**: Description of what we're generating documentation for, this can contain usage examples and can use the args array to pass names(e.g.: This method uses this methodology)  
+**Args**: Array of strings that describe the parameters of the method or class  
+**CodeExample**: A code example of how to use the method or class  
+  
+*Note: If generateForPackageAssembly is set to true, this will generate documentation for the library as well.*",
+            new []
+            {
+                "generateForPackageAssembly - Generate documentation for the DocumentationHelper library as well?"
+            }, 
+            @"```csharp
+DocumentationHelperTool.GenerateDocumentation(true); // Generates documentation for all assemblies including the DocumentationHelper.Library package assembly
+DocumentationHelperTool.GenerateDocumentation(false); // Generates documentation for all assemblies excluding the DocumentationHelper.Library package assembly
+```")]
+        public static IEnumerable<DocumentationStructure> GenerateDocumentation(bool generateForPackageAssembly = false)
+    {
+        EnsureReferencedAssembliesLoaded();
+
+        var assemblies = AppDomain.CurrentDomain.GetAssemblies()
+            .Where(a => !a.IsDynamic)
+            .Select(a =>
+                new DocumentationAssembly()
+                {
+                    AssemblyName = a.GetName(false)?.Name ?? nameof(a),
+                    Types = GetTypesWithDocumentationAttribute(a)
+                }).Where(x => x.Types.Any()).ToList();
+
+        if (!generateForPackageAssembly)
+        {
+            assemblies =
+                assemblies.Where(x => x.AssemblyName != typeof(DocumentationHelperTool).Assembly.GetName().Name)
+                    .ToList();
+        }
+
+        foreach (var assembly in assemblies)
+        {
+            foreach (var type in assembly.Types)
+            {
+                var doc = GetDocumentation(type, assembly.AssemblyName);
+                yield return doc;
+            }
+        }
+    }
+
+    static void EnsureReferencedAssembliesLoaded()
+    {
+        try
+        {
+            var loadedNames = AppDomain.CurrentDomain.GetAssemblies()
+                .Where(a => a.GetName(false) != null)
+                .Select(a => a.GetName(false).Name)
+                .ToHashSet(StringComparer.OrdinalIgnoreCase);
+
+            var deps = DependencyContext.Default?.RuntimeLibraries;
+            if (deps == null) return;
+
+            foreach (var lib in deps)
+            {
+                if (!loadedNames.Contains(lib.Name))
+                {
+                    try
+                    {
+                        Assembly.Load(new AssemblyName(lib.Name));
+                    }
+                    catch (Exception ex)
+                    {
+                        Console.Error.WriteLine($"warning OMEGA001: Failed to load assembly '{lib.Name}': {ex.Message}");
+                    }
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            // best-effort only
+            Console.Error.WriteLine($"warning OMEGA001: EnsureReferencedAssembliesLoaded failed: {ex.Message}");
+        }
+    }
+
+    static IEnumerable<Type> GetTypesWithDocumentationAttribute(Assembly assembly)
+    {
+        Type[] types;
+        try
+        {
+            types = assembly.GetTypes();
+        }
+        catch (ReflectionTypeLoadException ex)
+        {
+            types = ex.Types.Where(t => t != null).ToArray();
+        }
+
+        foreach (Type type in types)
+        {
+            if (type == null) continue;
+
+            var classHasDoc = type.GetCustomAttributes(typeof(DocumentationAttribute), true).Any();
+            var fieldsHaveDoc = type.GetFields()
+                .Any(f => f.GetCustomAttributes(typeof(DocumentationAttribute), true).Any());
+            var typesHaveDoc = type.GetProperties()
+                .Any(p => p.GetCustomAttributes(typeof(DocumentationAttribute), true).Any());
+            var methodsHaveDoc = type.GetMethods()
+                .Any(m => m.GetCustomAttributes(typeof(DocumentationAttribute), true).Any());
+
+            if (classHasDoc || fieldsHaveDoc || typesHaveDoc || methodsHaveDoc)
+            {
+                yield return type;
+            }
+        }
+    }
+
+        [Documentation(nameof(GetDocumentation), "Generates a DocumentationStructure object for the given Type and Assembly Name",
+            new []
+            {
+                "type - The Type to generate documentation for",
+                "assemblyName - The name of the assembly the Type belongs to"
+            },
+            @"```csharp
+ var doc = GetDocumentation(typeof(MyClass), ""MyAssembly"");
+```")]
+        static DocumentationStructure GetDocumentation(Type type, string assemblyName)
+        {
+            var classDocs = type.GetCustomAttributes(typeof(DocumentationAttribute), true)
+                .Select(x => (DocumentationAttribute)x);
+            
+            var fieldDocs = type.GetFields().SelectMany(f =>
+                f.GetCustomAttributes(typeof(DocumentationAttribute), true).Select(x => (DocumentationAttribute)x));
+            var propertyDocs = type.GetProperties().SelectMany(p =>
+                p.GetCustomAttributes(typeof(DocumentationAttribute), true).Select(x => (DocumentationAttribute)x));
+            var methodDocs = type.GetMethods().SelectMany(m =>
+                m.GetCustomAttributes(typeof(DocumentationAttribute), true).Select(x => (DocumentationAttribute)x));
+            
+            var docStructure = new DocumentationStructure(assemblyName, type.Name);
+
+            foreach (var doc in classDocs)
+            {
+                docStructure.AddDescription(new DocumentationDescription(doc.Title, doc.Description, doc.Args, doc.CodeExample));
+            }
+
+            foreach (var doc in fieldDocs)
+            {
+                docStructure.AddDescription(new DocumentationDescription(doc.Title, doc.Description, doc.Args, doc.CodeExample));
+            }
+
+            foreach (var doc in propertyDocs)
+            {
+                docStructure.AddDescription(new DocumentationDescription(doc.Title, doc.Description, doc.Args, doc.CodeExample));
+            }
+
+            foreach (var doc in methodDocs)
+            {
+                docStructure.AddDescription(new DocumentationDescription(doc.Title, doc.Description, doc.Args, doc.CodeExample));
+            }
+
+            return docStructure;
+        }
+        
+        static Dictionary<string, string> loadedXmlDocumentation =
+            new Dictionary<string, string>();
+        public static void LoadXmlDocumentation(string xmlDocumentation)
+        {
+            using (XmlReader xmlReader = XmlReader.Create(new StringReader(xmlDocumentation)))
+            {
+                while (xmlReader.Read())
+                {
+                    if (xmlReader.NodeType == XmlNodeType.Element && xmlReader.Name == "member")
+                    {
+                        string raw_name = xmlReader["name"];
+                        loadedXmlDocumentation[raw_name] = xmlReader.ReadInnerXml();
+                    }
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,11 @@
+using System;
+using System.Collections.Generic;
+
+namespace OmegaLeo.HelperLib.Documentation.Models
+{
+    public class DocumentationAssembly
+    {
+        public string AssemblyName;
+        public IEnumerable<Type> Types;
+    }
+}
@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using OmegaLeo.HelperLib.Shared.Attributes;
+
+namespace OmegaLeo.HelperLib.Documentation.Models
+{
+
+    public class DocumentationStructure
+    {
+        public string AssemblyName;
+        public string ClassName;
+        public List<DocumentationDescription> Descriptions;
+
+        public DocumentationStructure(string assemblyName, string className)
+        {
+            AssemblyName = assemblyName;
+            ClassName = className;
+            Descriptions = new List<DocumentationDescription>();
+        }
+
+        public void AddDescription(DocumentationDescription description)
+        {
+            Descriptions.Add(description);
+        }
+    }
+
+    public class DocumentationDescription
+    {
+        public string Title;
+        public string Description;
+        public string[] Parameters;
+        public string CodeExample = string.Empty;
+
+        [Documentation(nameof(DocumentationDescription), "Description of the current Documented object", new []
+        {
+            "title - Name of the object",
+            "description - Description of what the object does",
+            "parameters - The parameters for the object (in case of a method with parameters)",
+            "codeExample - Code example of how to use the object"
+        })]
+        public DocumentationDescription(string title, string description, string[] parameters = default, string codeExample = "")
+        {
+            Title = title;
+            Description = description;
+            Parameters = parameters ?? Array.Empty<string>();
+            CodeExample = codeExample;
+        }
+    }
+}
@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>netstandard2.1</TargetFramework>
+        <Nullable>enable</Nullable>
+        <RootNamespace>OmegaLeo.HelperLib.Documentation</RootNamespace>
+        <Version>0.0.2</Version>
+        <Title>Omega Leo's Helper Library</Title>
+        <Authors>Nuno "Omega Leo" Diogo</Authors>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+        <PackageProjectUrl>https://github.com/omegaleo/HelperLib</PackageProjectUrl>
+        <RepositoryUrl>https://github.com/omegaleo/HelperLib</RepositoryUrl>
+        <PublishRepositoryUrl>true</PublishRepositoryUrl>
+        <PackageLicenseExpression>AGPL-3.0-only</PackageLicenseExpression>
+        <PackageTags>csharp;dotnet;utility;helper;documentation;</PackageTags>
+        <RepositoryType>git</RepositoryType>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    </PropertyGroup>
+    <ItemGroup>
+      <PackageReference Include="Microsoft.Extensions.DependencyModel" Version="10.0.2" />
+    </ItemGroup>
+    <ItemGroup>
+      <Folder Include="Attributes\" />
+    </ItemGroup>
+    <ItemGroup>
+      <ProjectReference Include="..\OmegaLeo.HelperLib.Shared\OmegaLeo.HelperLib.Shared.csproj" />
+    </ItemGroup>
+
+</Project>