@@ -10,19 +10,19 @@ DocFX is used to generate the documentation for this library. There is confusion
1010*** DOES NOT*** mean that the default+modern template is unusable for hosted static site
1111scenarios like 'gh-pages' in GitHub. It only means that the TOC support will
1212*** require*** a hosted site to provide the contents needed by the generated TOC client side
13- scripting. That's it. Don't fear the built-in templates (Despite the lack of decent docs
14- explaining the details [ Yeah, this project previously fell into those gaps and even
13+ scripting. That's it. Don't fear the built-in templates - despite the lack of decent docs
14+ explaining the details! [ Yeah, this project previously fell into those gaps and even
1515constructed a complete custom template to deal with it... Sigh, what a waste of time...
16- :facepalm : ] )
16+ :facepalm : ]
1717
1818## Changes Over Time
1919DocFX has obsoleted the ` docfxconsole ` NuGet package that was used to run docfx for a
2020project via MSBUILD. Instead it focused on a .NET tool to do it all via the command line.
21- Ultimately the docfx.json serves as the "project" file for the different site builds.
22- The PowerShell script ` Build-Docs.ps1 ` was updated to use the new tool directly. Using that
23- script should have little or no impact on the overall flow. There is a "no-targets" project
24- in the solution to enable easier access to the input files but does not itself, generate any
25- docs - it's just a placeholder.
21+ Ultimately the docfx.json serves as the corellary to a "project" file for the different site
22+ builds. The PowerShell script ` Build-Docs.ps1 ` was updated to use the new tool directly.
23+ Using that script should have little or no impact on the overall flow. There is a
24+ "no-targets" project in the solution to enable easier access to the input files but does not
25+ itself, generate any docs - it's just a placeholder.
2626
2727## Files used by the docs generation
2828There are a lot of files used to generate the docs and the concept of a Table of Contents
@@ -77,3 +77,76 @@ Since this is generated it is listed in the [.gitignore](#gitignore) file.
7777#### Library Content
7878These folders (named after the ` * ` portion of the [ api-* ] ( #api-* ) folder names contains
7979manually written additional files, articles, samples etc... related to a given library.
80+
81+ ## Guid to wrting XML DOC comments
82+ When dealing with doc comments the XML can get in the way of general readability of the
83+ source code. There is an inherent tension beween how a particular editor renders the docs
84+ for a symbol/method (VS calls this "Quick Info") and how it is rendered in the final
85+ documentation by docfx. This guides general use to simplify things as much as possible.
86+
87+ ### Lists
88+ The largest intrusion of the XML into the source is that of lists. The XML doc comments
89+ official support is to use the ` <list> ` tag. However, that is VERY intrusive and doesn't
90+ easily support sub-lists. Consider:
91+
92+ ``` C#
93+ /// Additional steps might include:
94+ /// <para
95+ /// <list type " number"
96+ /// <item item
97+ /// <item item
98+ /// <item
99+ /// Act on the results as proper for the application
100+ /// <list type " number"
101+ /// <item item
102+ /// <item item
103+ /// </list
104+ /// </item
105+ /// </list
106+ /// </para
107+ ```
108+
109+ versus:
110+ ``` C#
111+ /// Additional steps might include:<br
112+ ///
113+ /// 1) App specific Validation/semantic analysis<br
114+ /// 2) Binding of results to an app specific type<br
115+ /// 3) Act on the results as proper for the application<br
116+ /// a. This might include actions parsed but generally isolating the various stages is an easier to understand/maintain model<br
117+ /// b. Usually this is just app specific code that uses the bound results to adapt behavior<br
118+ ///
119+ ```
120+
121+ Which one would *** YOU*** rather encounter in code? Which one is easier to understand when
122+ reading the source? This repo chooses the latter. (If you favor the former, perhaps you
123+ should reconsider... :grinning : )
124+
125+ #### How to handle lists
126+ There is little that can be done to alter the rendering of any editor support, at most an
127+ editor might allow specification of a CSS file, but that is the lowest priority of doc
128+ comments. Readability by maintainers of the docs AND the rendering for final docs used by
129+ consumers of of VASTLY higher importance. Still, the editor rendering *** is*** of value to
130+ maintainers so should not be forgotten as it can make a "right mess of things" even if they
131+ render properly in final docs.
132+
133+ ##### Guidance
134+ 1 ) *** DO NOT*** use ` <para> ` tags to include any lists
135+ a) Doing so will break the docfx rendering that allows for markdown lists
136+ 2 ) Use `</br >' tags to indicate a line break. This is used by the editor rendering to mark
137+ the end of a line and start a new one. (Stops auto reflow)
138+ 3 ) Accept that the in edotr rendering might "trim" the lines it shows, eliminating any
139+ indentation.
140+ a) Sadly, there is no avoiding this. Addition of any sort of "markup" to control that
141+ will interfere with the readability AND the final docs rendering.
142+ 4 ) Always use a different numbering style for sub lists/items
143+ b) This will at least show in the in-editor rendering as distinct sub items so if
144+ everything is trimmed it is at least a distinct pattern that is readable.
145+ 5 ) *** DO NOT*** put lists in any place other than inside a ` remarks ` region
146+ a) Usually, the remarks comments are not even rendered as the most useful part is the
147+ API signaure and parameter info. Different editors may allow control of that.
148+ i) In VS [ 2019|2022] for C# it is controlled by
149+ ` Text Editor > C# > Advanced > Editor Help: "Show remarks in Quick Info." `
150+ ii) Turning this off can greatly reduce the noise AND reduce the problems of
151+ different rende
152+
0 commit comments