{"id":27122336,"url":"https://github.com/andrei15193/codemap","last_synced_at":"2025-08-19T00:09:21.032Z","repository":{"id":157925580,"uuid":"174802746","full_name":"Andrei15193/CodeMap","owner":"Andrei15193","description":"An extensible tool for generating documentation for your .NET libraries. Generate HTML, Markdown or in any other format, customise the documentation at your discretion.","archived":false,"fork":false,"pushed_at":"2023-11-29T10:47:10.000Z","size":2985,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-08-01T05:20:55.592Z","etag":null,"topics":["documentation","documentation-code","documentation-generator","documentation-tool","generator","html","site-generator"],"latest_commit_sha":null,"homepage":"https://andrei15193.github.io/CodeMap/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Andrei15193.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-03-10T09:30:22.000Z","updated_at":"2025-08-01T03:56:11.000Z","dependencies_parsed_at":"2023-11-29T11:29:21.173Z","dependency_job_id":"a200b436-aae4-4257-885c-a6cf1351dc6f","html_url":"https://github.com/Andrei15193/CodeMap","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Andrei15193/CodeMap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andrei15193%2FCodeMap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andrei15193%2FCodeMap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andrei15193%2FCodeMap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andrei15193%2FCodeMap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Andrei15193","download_url":"https://codeload.github.com/Andrei15193/CodeMap/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andrei15193%2FCodeMap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271078587,"owners_count":24695473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-code","documentation-generator","documentation-tool","generator","html","site-generator"],"created_at":"2025-04-07T11:35:58.903Z","updated_at":"2025-08-19T00:09:21.003Z","avatar_url":"https://github.com/Andrei15193.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build and Deploy](https://github.com/Andrei15193/CodeMap/workflows/Build%20and%20Deploy/badge.svg)\n\nVisual Studio enables developers to write comprehensive documentation inside\ntheir code using XML in three slashed comments,\nsee [XML Documentation Comments (C# Programming Guide)](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) for\nmore details about supported tags.\n\nWhen we build a project that has been configured to generate XML documentation\nfiles (simply specify the output path where resulting files should be saved)\nVisual Studio will look for this file and display the respective documentation\nin IntelliSense.\n\nThis is great and all library owners should be writing documentation like this\nin their code, however there aren't that many tools out there that allow us to\ntransform the XML generated documentation into something else, say JSON or\ncustom HTML, to display the exact same documentation on the project's website.\n\nHaving a single source for documentation is the best way to ensure consistency,\nwhat you see in code is what you see on the project's website. There are no\ndiscrepancies. Writing all documentation in code may upset developers, but\nafter all they know best what the code they are writing is all about.\n\nCodeMap aims to bring a tool into the developers hands that allows them to\ngenerate any output format they wish from a given assembly and associated\nXML documentation.\n\nThis is done following the visitor design pattern, an assembly is being visited\nand all elements that make up an assembly get their turn. When you want to\ngenerate a specific output (say Markdown or Creole) you simply implement your\nown visitor.\n\nThere are some elements that do not have XML documentation correspondents, such\nas assemblies, modules and namespaces. You cannot write documentation for\nneither in code and have it generated in the resulting XML document.\n\nThis tool does not work directly on the XML file but rather on a representation\nof the file (XDocument), this allows for the document to be loaded, updated if\nnecessary and only then processed. This enables the tool to support additions\nto the standard XML document format allowing for extra documentation to be\nmanually added. If you want to add specific documentation to a namespace, you\ncan, but you have to do it manually which means you follow the XML document\nstructure as well.\n\nThis project exposes an XML Schema (.xsd) that is used for validating an XML\ndocument containing documentation to ensure that it is being correctly\nprocessed.\n\nExceptions\n----------\n\nSome elements are ignored when processing the XML document because they either\nare complex to use or there is little support for them.\n\n* [include](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/include)\nis being ignored because its usage is rather complex and can be misleading.\nThe documentation is being kept separate from the source code which can easily\nlead to discrepancies when changes to code occur.\n\n* [permission](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/permission)\nis being ignored because its usage is more of an edge case and code permissions\nare not supported in .NET Core making this element obsolete in this case.\n\nInterpretations\n---------------\n\nThere are XML elements defined for various sections and limited markup support.\nThe main sections for documentation are the following:\n\n* [summary](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/summary)\n* [typeparam](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/typeparam) (available only for types and methods)\n* [param](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/param) (available only for delegates, constructors, methods, properties with parameters)\n* [returns](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/returns) (available only for delegates and methods with result)\n* [exception](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/exception) (available only for delegates, constructors, methods and properties)\n* [remarks](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/remarks)\n* [example](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/example)\n* [value](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/value) (available only for properties)\n* [seealso](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/seealso)\n\nAll of the above sections can contain documentation made out of blocks, text\nand limited markup. [seealso](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/seealso) does\nnot contain any content and are interpreted as references.\n\nThe content blocks are made using the following tags:\n\n* [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para)\n* [code](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code)\n* [list](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list)\n\nIt is not mandatory to specify the [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para) element\nbecause it is inferred. It is mandatory to do so only when you want to\ndistinguish two paragraphs that are one after the other, but if there is plain\ntext that has a [code](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code)\nor a [list](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list) element\nthen the text before the respective tag is considered a paragraph and the text\nafterwards is considered a separate paragraph.\n\nFor instance, the following [returns](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/returns) section\ncontains three paragraphs, a code block and a list.\n\n```xml\n\u003cremarks\u003e\nThis is my first paragraph.\n\u003ccode\u003e\nThis is a code block\n\u003c/code\u003e\nThis is my second paragraph.\n\u003clist\u003e\n    \u003citem\u003eItem 1\u003c/item\u003e\n    \u003citem\u003eItem 2\u003c/item\u003e\n    \u003citem\u003eItem 3\u003c/item\u003e\n\u003c/list\u003e\nThis is my third paragraph.\n\u003c/remarks\u003e\n```\n\nTo distinguish two paragraphs one after the other you need to use the [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para) tag.\n\n```xml\n\u003cremarks\u003e\n\u003cpara\u003e\n    This is my first paragraph.\n\u003c/para\u003e\n\u003cpara\u003e\n    This is my second paragraph.\n\u003c/para\u003e\n\u003c/remarks\u003e\n```\n\nEach content block can contain plain text and limited markup using the following tags:\n\n* [c](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code-inline)\n* [see](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/see)\n* [paramref](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/paramref)\n* [typeparamref](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/typeparamref)\n\nSome XML elements lack a proper documentation and are not properly interpreted\nby Visual Studio.\n\n[List](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list) is\none of these elements, regardless of how you define the list element, Visual\nStudio will display the contents as plain text. This is understandable, there\nshould not be such complex markup in the summary of a method or parameter\ndescription.\n\nOne the other hand, the lack of documentation for this element and the lack of\nproper interpretation allows for more flexibility when it comes to parsing\nlists. This tool parses lists as follows:\n\n### Simple Lists\n\nThis corresponds to list type `bullet` and `number` that have no `listheader`\nelement.\n\nTo define a list simply use the `list` element, specify a type (the default is\n`bullet`) and then define each item using an `item` element. Optionally include\na `description` subelement (this is more for compliance with the documentation,\nhaving a `description` element or not makes no difference).\n\n#### Examples\n\nBullet (unordered) list:\n\n```xml\n\u003clist type=\"bullet\"\u003e\n    \u003citem\u003ethis is an item\u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003ethis is an item using description, it is the same as the first one\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003ethe description element is optional, use at your discretion\u003c/item\u003e\n\u003c/list\u003e\n```\n\nNumber (ordered) list:\n\n```xml\n\u003clist type=\"number\"\u003e\n    \u003citem\u003efirst item\u003c/item\u003e\n    \u003citem\u003esecond item\u003c/item\u003e\n    \u003citem\u003ethird item\u003c/item\u003e\n\u003c/list\u003e\n```\n\n### Definition Lists\n\nThis is where it can get a bit confusing. The definition list is inferred by\nthe given list type (`bullet` or `number`) or lack of this attribute.\nDefinition lists cannot be ordered or unordered, they define a list of terms.\nThis makes the type attribute rather useless in this case, it can be safely\nomitted since the default is `bullet` and alligns with the interpretation.\n\nTo create a definition list it must either have a title or one of its items\nto contain the `term` element. The title is optional, however if the `list`\nelement is empty it will not be inferred as a definition list!\n\nOptionally, a definition list can have a title which is defined using the\n`listheader` element. The title can be written directly in the element or\ncan be wrapped in a `term` element.\n\n#### Examples\n\nSimple definition list:\n\n```xml\n\u003clist\u003e\n    \u003citem\u003e\n        \u003cterm\u003eException\u003c/term\u003e\n        \u003cdescription\u003eDescribes an abnormal behaviour\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eLogging\u003c/term\u003e\n        \u003cdescription\u003eSomething we should be doing\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eHTTP\u003c/term\u003e\n        \u003cdescription\u003eHyperText Transfer Protocol, today's standard for communication\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\nDefinition list with title:\n\n```xml\n\u003clist\u003e\n    \u003clistheader\u003eMusic Genres\u003c/listheader\u003e\n    \u003citem\u003e\n        \u003cterm\u003ePop\u003c/term\u003e\n        \u003cdescription\u003eVery popular (hence the name) genre, mostly singing nonsence.\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eRock\u003c/term\u003e\n        \u003cdescription\u003eExperiences with depth that are very musical with some grotesque exceptions that seem more like yelling than singing.\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eEDM\u003c/term\u003e\n        \u003cdescription\u003eElectronic Dance Music, less singing mostly used for background noise or to help get into a specific mood.\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\nSame definition list, we can wrap the title in a `term` element to conform with\nthe documentation:\n\n```xml\n\u003clist\u003e\n    \u003clistheader\u003e\n        \u003cterm\u003eMusic Genres\u003c/term\u003e\n    \u003c/listheader\u003e\n    \u003citem\u003e\n        \u003cterm\u003ePop\u003c/term\u003e\n        \u003cdescription\u003eVery popular (hence the name) genre, mostly singing nonsence.\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eRock\u003c/term\u003e\n        \u003cdescription\u003eExperiences with depth that are very musical with some grotesque exceptions that seem more like yelling than singing.\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cterm\u003eEDM\u003c/term\u003e\n        \u003cdescription\u003eElectronic Dance Music, less singing mostly used for background noise or to help get into a specific mood.\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\nA definition list without a term for its second item:\n\n```xml\n\u003clist\u003e\n    \u003citem\u003e\n        \u003cterm\u003eLOL\u003c/term\u003e\n        \u003cdescription\u003eUsually meaning laughing out loud, can be confused with League of Legends, a very popular video game.\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eFor some reason I forgot to mention the term I am currently describing, Infer this!\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\n### Tables\n\nThis is where things will get a bit interesting. Tables are useful in a lot of\nscenarios, however there is no explicit syntax for them.\n\nTo define a table specify the `type` of a `list` to `table`. To define the\nheader rows (if any) use the `listheader` element, to define each column\nheader specify multiple `term` elements.\n\nTo define each row use the `item` element and for each column use a\n`description` element.\n\nThe number of columns is determined by the maximum number of `term` or\n`description` elements found in an enclosing element (`listheader` or `item`).\nIf there are missing values for a column header or row then they will be filled\nwith blank.\n\n#### Examples\n\nSimple table:\n\n```xml\n\u003clist type=\"table\"\u003e\n    \u003clistheader\u003e\n        \u003cterm\u003eColumn 1\u003c/term\u003e\n        \u003cterm\u003eColumn 2\u003c/term\u003e\n    \u003c/listheader\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 1, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 1, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 2, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 2, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 3, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 3, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\nTable without heading:\n\n```xml\n\u003clist type=\"table\"\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 1, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 1, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 2, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 2, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 3, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 3, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```\n\nTable with missing values for last column:\n\n```xml\n\u003clist type=\"table\"\u003e\n    \u003clistheader\u003e\n        \u003cterm\u003eColumn 1\u003c/term\u003e\n    \u003c/listheader\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 1, Column 1\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 2, Column 1\u003c/description\u003e\n        \u003cdescription\u003eRow 2, Column 2\u003c/description\u003e\n    \u003c/item\u003e\n    \u003citem\u003e\n        \u003cdescription\u003eRow 3, Column 1\u003c/description\u003e\n    \u003c/item\u003e\n\u003c/list\u003e\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrei15193%2Fcodemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrei15193%2Fcodemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrei15193%2Fcodemap/lists"}