-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathAssemblyDoc.cs
More file actions
153 lines (152 loc) · 9.41 KB
/
AssemblyDoc.cs
File metadata and controls
153 lines (152 loc) · 9.41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
namespace ROBdk97.XmlDocToMd;
/// <summary>
/// Converts XML documentation files into GitHub-Flavored Markdown, producing output
/// compatible with <a href="https://www.mkdocs.org/">MkDocs</a> and GitHub Pages.
/// <para>
/// The tool reads the standard <tt>.xml</tt> file emitted by the C# compiler alongside
/// the compiled assembly, enriches member signatures via Reflection, and writes a
/// structured <tt>.md</tt> file.
/// </para>
/// <para>
/// See the <see cref="Cli.Options"/> class for every available command-line parameter, and
/// the <i>Supported XML Documentation Tags</i> section in <a href="AssemblyDoc.cs">AssemblyDoc</a>
/// remarks for the full list of handled tags.
/// </para>
/// <para>
/// Use <see cref="Cli.Settings.FilesToIgnore"/> to skip files during batch conversion.
/// The wildcard <tt>*</tt> is supported, for example <tt>System*</tt>, <tt>Microsoft*</tt>.
/// </para>
/// <para>
/// The tool looks for an empty public class named <a href="AssemblyDoc.cs">AssemblyDoc</a> (abstract is
/// recommended) and places its XML documentation at the top of the generated Markdown
/// file. This is used to create a general documentation overview with references to the
/// most important parts and a high-level description, similar to the main section of a
/// README.
/// </para>
/// <note>
/// Because the tool uses <see cref="ReflectionHelper">Reflection</see> to resolve member types and visibility, the
/// compiled <tt>.dll</tt> must reside in the same directory as the <tt>.xml</tt> file.
/// Conversion still succeeds without the DLL, but type information in tables will be
/// reduced to the raw prefix letter (<tt>F</tt>, <tt>P</tt>, …).
/// </note>
/// <example>
/// <h4>Basic single-file conversion</h4>
/// <code lang="bat">
/// XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\output.md"
/// </code>
///
/// <h4>Batch conversion — search a directory tree</h4>
/// <para>
/// Searches <tt>C:\Project\Docs</tt> for sub-folders named <tt>Release</tt>, converts
/// every <tt>.xml</tt> found inside, and writes <tt>.md</tt> files to the output dir:
/// </para>
/// <code lang="bat">
/// XmlDocToMd.exe -s "C:\Project\Docs" -d "Release" -o "C:\Project\MarkdownDocs"
/// </code>
///
/// <h4>With a secondary (backup) output directory</h4>
/// <code lang="bat">
/// XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\Markdown\output.md" -l "C:\Backup\Docs"
/// </code>
///
/// <h4>Soft tag handling — warn instead of throwing</h4>
/// <code lang="bat">
/// XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\output.md" -u Warn
/// </code>
///
/// <h4>GitHub-flavored URLs + README output</h4>
/// <code lang="bat">
/// XmlDocToMd.exe -i "C:\Docs\input.xml" -o "C:\Docs\README.md" -g -r
/// </code>
///
/// <h4>Visual Studio post-build event (XMLtoMD configuration)</h4>
/// <code lang="xml"><![CDATA[
///<Target Name="PostBuild" AfterTargets="PostBuildEvent" Condition="'$(ConfigurationName)' == 'XMLtoMD'">
/// <Exec Command="call "$(TargetDir)$(TargetName).exe" -s "$(ProjectDir)\" -d "$(ConfigurationName)" -o "$(ProjectDir)\" -g -r" />
///</Target>]]>
/// </code>
/// </example>
/// <h3>Supported XML Documentation Tags</h3>
/// </summary>
/// <remarks>
/// <h4>Standard C# XML Doc Tags</h4>
/// <list type="table">
/// <listheader><term>Tag</term><description>Markdown output</description></listheader>
/// <item><term><c>doc</c></term><description>Top-level document root — emits an <c>#</c> heading with the assembly name.</description></item>
/// <item><term><c>summary</c></term><description>Rendered as a plain paragraph below the member heading.</description></item>
/// <item><term><c>remarks</c></term><description>Rendered as a paragraph block below the summary.</description></item>
/// <item><term><c>returns</c></term><description>Emits a <b>Returns:</b> line with the resolved return type.</description></item>
/// <item><term><c>value</c></term><description>Emits a <b>Value:</b> line for property descriptions.</description></item>
/// <item><term><c>example</c></term><description>Rendered under an <c>##### Example</c> sub-heading.</description></item>
/// <item><term><c>param</c></term><description>Collected into a two-column Markdown table (Name / Description).</description></item>
/// <item><term><c>typeparam</c></term><description>Collected into a two-column Generics table.</description></item>
/// <item><term><c>exception</c></term><description>Emits a <b>Throws:</b> linked entry per exception type.</description></item>
/// <item><term><c>inheritdoc</c></term><description>Emits <i>Inherited from `BaseType`</i>. The <c>cref</c> attribute controls the display name.</description></item>
/// </list>
///
/// <h4>Cross-Reference Tags</h4>
/// <list type="table">
/// <listheader><term>Tag / attribute</term><description>Markdown output</description></listheader>
/// <item><term><c>see cref=""</c></term><description>Inline hyperlink to the referenced member.</description></item>
/// <item><term><c>see langword=""</c></term><description>Renders the keyword as inline code, e.g. <see langword="null"/>, <see langword="true"/>.</description></item>
/// <item><term><c>see href=""</c></term><description>Currently not rendered as a link. Use <c>a href=""</c> for explicit URL links.</description></item>
/// <item><term><c>seealso</c></term><description>Appended to a <i>See also</i> bullet list at the end of the member block.</description></item>
/// <item><term><c>paramref</c></term><description>Renders the parameter name as inline code.</description></item>
/// <item><term><c>typeparamref</c></term><description>Renders the type-parameter name as inline code.</description></item>
/// </list>
///
/// <h4>List Tags</h4>
/// <tip>
/// Use <c>type="table"</c> for two-column reference tables, <c>type="number"</c> for
/// step-by-step instructions, and <c>type="bullet"</c> (the default) for unordered lists.
/// </tip>
/// <list type="table">
/// <listheader><term>Tag</term><description>Description</description></listheader>
/// <item><term><c>list type="bullet"</c></term><description>Unordered bullet list — each <c>item</c> becomes a <c>-</c> entry.</description></item>
/// <item><term><c>list type="number"</c></term><description>Ordered list — each <c>item/description</c> becomes a numbered entry.</description></item>
/// <item><term><c>list type="table"</c></term><description>Pipe table — <c>listheader</c> provides column headers; each <c>item</c> becomes a row.</description></item>
/// <item><term><c>listheader</c></term><description>Column header row for <c>type="table"</c> lists.</description></item>
/// <item><term><c>item</c></term><description>A single list entry; contains <c>term</c> and/or <c>description</c>.</description></item>
/// <item><term><c>term</c></term><description>Bold label in a table row or bullet entry.</description></item>
/// <item><term><c>description</c></term><description>Description text within an <c>item</c>.</description></item>
/// </list>
///
/// <h4>Inline Formatting Tags</h4>
/// <list type="table">
/// <listheader><term>Tag</term><description>Markdown output</description></listheader>
/// <item><term><c>c</c></term><description>Inline code span: <c>`text`</c></description></item>
/// <item><term><c>tt</c></term><description>Teletype / monospace — same output as <c>c</c>: <c>`text`</c></description></item>
/// <item><term><c>b</c></term><description><b>Bold</b> text: <c>**text**</c></description></item>
/// <item><term><c>strong</c></term><description><b>Bold</b> text: <c>**text**</c></description></item>
/// <item><term><c>i</c></term><description><i>Italic</i> text: <c>*text*</c></description></item>
/// <item><term><c>u</c></term><description>Currently rendered as bold text: <c>**text**</c></description></item>
/// <item><term><c>para</c></term><description>Paragraph break inside a block element.</description></item>
/// <item><term><c>code</c></term><description>Fenced code block. Use the <c>lang</c> attribute for syntax highlighting, e.g. <c>lang="csharp"</c>.</description></item>
/// </list>
///
/// <h4>HTML Pass-Through Tags</h4>
/// <list type="table">
/// <listheader><term>Tag</term><description>Markdown output</description></listheader>
/// <item><term><c>a href="…"</c></term><description>Hyperlink: <c>[text](url)</c></description></item>
/// <item><term><c>br</c></term><description>Hard line break.</description></item>
/// <item><term><c>h1</c> – <c>h4</c></term><description>ATX headings at the corresponding level.</description></item>
/// </list>
///
/// <h4>GFM Alert Blocks <i>(DocFX / Sandcastle compatibility)</i></h4>
/// <note>
/// These tags map to GitHub-Flavored Markdown alert syntax (<c>> [!NOTE]</c> etc.)
/// and render as coloured callout boxes on GitHub and MkDocs Material.
/// </note>
/// <list type="table">
/// <listheader><term>Tag</term><description>GFM alert type</description></listheader>
/// <item><term><c>note</c></term><description><c>> [!NOTE]</c> — informational callout.</description></item>
/// <item><term><c>tip</c></term><description><c>> [!TIP]</c> — helpful suggestion.</description></item>
/// <item><term><c>important</c></term><description><c>> [!IMPORTANT]</c> — key information.</description></item>
/// <item><term><c>warning</c></term><description><c>> [!WARNING]</c> — potential pitfall.</description></item>
/// <item><term><c>caution</c></term><description><c>> [!CAUTION]</c> — dangerous action ahead.</description></item>
/// </list>
/// </remarks>
public abstract class AssemblyDoc
{
// No implementation required.
}