feat: Add doc comments to docfx.json related config files. (dotnet#8969)

* Add doc comments

* Add warning suppression for obsolete

* Add warning suppression for obsolete

* Update src/Docfx.App/Config/BuildJsonConfig.cs

Co-authored-by: Yufei Huang <[email protected]>

* Add obsolete attributes that is mentioned in review comments. and fix some comment.

* Update DocumentBuilderWrapper.cs

* fix .gitignore file for docfx init

---------

Co-authored-by: Yufei Huang <[email protected]>

src/Docfx.App/Config/BuildJsonConfig.cs

@@ -9,6 +9,10 @@
 
 namespace Docfx;
 
+/// <summary>
+/// BuildJsonConfig.
+/// </summary>
+/// <see href="https://dotnet.github.io/docfx/reference/docfx-json-reference.html#12-properties-for-build"/>
 [Serializable]
 internal class BuildJsonConfig
 {
@@ -18,34 +22,66 @@ internal class BuildJsonConfig
     [JsonIgnore]
     private Dictionary<string, GroupConfig> _groups;
 
+    /// <summary>
+    /// Contains all the files to generate documentation, including metadata yml files and conceptual md files.
+    /// </summary>
     [JsonProperty("content")]
     public FileMapping Content { get; set; }
 
+    /// <summary>
+    /// Contains all the resource files that conceptual and metadata files dependent on, e.g. image files.
+    /// </summary>
     [JsonProperty("resource")]
     public FileMapping Resource { get; set; }
 
+    /// <summary>
+    /// Contains all the conceptual files which contains yaml header with uid and is intended to override the existing metadata yml files.
+    /// </summary>
     [JsonProperty("overwrite")]
     public FileMapping Overwrite { get; set; }
 
+    /// <summary>
+    /// Specifies pairing that is used for folder redirection rules.
+    /// </summary>
+    [Obsolete("May be removed in a future release.")]
     [JsonProperty("pairing")]
     public List<ContentPairingInfo> Pairing { get; set; }
 
+    /// <summary>
+    /// Specifies the tags of xrefmap.
+    /// </summary>
     [JsonProperty("xrefTags")]
     public ListWithStringFallback XrefTags { get; set; }
 
+    /// <summary>
+    /// Specifies the urls of xrefmap used by content files. Supports local file path and HTTP/HTTPS urls.
+    /// </summary>
     [JsonProperty("xref")]
     public ListWithStringFallback XRefMaps { get; set; }
 
+    /// <summary>
+    /// Defines the output folder of the generated build files.
+    /// </summary>
+    [Obsolete("Use output instead.")]
     [JsonProperty("dest")]
     public string Destination { get; set; }
 
+    /// <summary>
+    /// Defines the output folder of the generated build files.
+    /// </summary>
     [JsonProperty("output")]
     public string Output { get; set; }
 
+    /// <summary>
+    /// Contains metadata that will be applied to every file, in key-value pair format.
+    /// </summary>
     [JsonProperty("globalMetadata")]
     [JsonConverter(typeof(JObjectDictionaryToObjectDictionaryConverter))]
     public Dictionary<string, object> GlobalMetadata { get; set; }
 
+    /// <summary>
+    /// Specify a list of JSON file path containing globalMetadata settings.
+    /// </summary>
     [JsonProperty("globalMetadataFiles")]
     public ListWithStringFallback GlobalMetadataFilePaths { get; set; } = new ListWithStringFallback();
 
@@ -59,51 +95,119 @@ internal class BuildJsonConfig
     [JsonProperty("fileMetadata")]
     public Dictionary<string, FileMetadataPairs> FileMetadata { get; set; }
 
+    /// <summary>
+    /// Specify tag parameters that are used by SchemaDrivenDocumentProcessor 
+    /// </summary>
+    [Obsolete("May be removed in a future release.")]
     [JsonProperty("tagParameters")]
     public Dictionary<string, JArray> TagParameters { get; set; }
 
+    /// <summary>
+    /// Specify a list of JSON file path containing fileMetadata settings.
+    /// </summary>
     [JsonProperty("fileMetadataFiles")]
     public ListWithStringFallback FileMetadataFilePaths { get; set; } = new ListWithStringFallback();
 
+    /// <summary>
+    /// The templates applied to each file in the documentation. It can be a string or an array.
+    /// The latter ones will override the former ones if the name of the file inside the template collides.
+    /// If omitted, embedded default template will be used.
+    /// </summary>
     [JsonProperty("template")]
     public ListWithStringFallback Templates { get; set; } = new ListWithStringFallback();
 
+    /// <summary>
+    /// The themes applied to the documentation.
+    /// Theme is used to customize the styles generated by template.
+    /// It can be a string or an array.
+    /// The latter ones will override the former ones if the name of the file inside the template collides.
+    /// If omitted, no theme will be applied, the default theme inside the template will be used.
+    /// </summary>
     [JsonProperty("theme")]
     public ListWithStringFallback Themes { get; set; }
 
+    /// <summary>
+    /// Specify PostProcessor array.
+    /// Build-in HtmlProcessor is automatically added by default.
+    /// </summary>
+    ///  <example>
+    ///  <code>
+    ///  "postProcessors": ["ExtractSearchIndex"]
+    ///  </code>
+    ///  </example>
     [JsonProperty("postProcessors")]
     public ListWithStringFallback PostProcessors { get; set; } = new ListWithStringFallback();
 
+    /// <summary>
+    /// Run in debug mode. With debug mode, raw model and view model will be exported
+    /// automatically when it encounters error when applying templates.
+    /// If not specified, it is false
+    /// </summary>
     [JsonProperty("debug")]
     public bool? EnableDebugMode { get; set; }
 
+    /// <summary>
+    /// The output folder for files generated for debugging purpose when in debug mode.
+    /// If not specified, it is ${TempPath}/docfx
+    /// </summary>
     [JsonProperty("debugOutput")]
     public string OutputFolderForDebugFiles { get; set; }
 
+    /// <summary>
+    /// If set to true, data model to run template script will be extracted in .raw.model.json extension.
+    /// </summary>
     [JsonProperty("exportRawModel")]
     public bool? ExportRawModel { get; set; }
 
+    /// <summary>
+    /// Specify the output folder for the raw model.
+    /// If not set, the raw model will be generated to the same folder as the output documentation.
+    /// </summary>
     [JsonProperty("rawModelOutputFolder")]
     public string RawModelOutputFolder { get; set; }
 
+    /// <summary>
+    /// If set to true, data model to apply template will be extracted in .view.model.json extension.
+    /// </summary>
     [JsonProperty("exportViewModel")]
     public bool? ExportViewModel { get; set; }
 
+    /// <summary>
+    /// Specify the output folder for the view model.
+    /// If not set, the view model will be generated to the same folder as the output documentation.
+    /// </summary>
     [JsonProperty("viewModelOutputFolder")]
     public string ViewModelOutputFolder { get; set; }
 
+    /// <summary>
+    /// If set to true, template will not be actually applied to the documents.
+    /// This option is always used with --exportRawModel or --exportViewModel is set so that only raw model files or view model files are generated.
+    /// </summary>
     [JsonProperty("dryRun")]
     public bool? DryRun { get; set; }
 
+    /// <summary>
+    /// Set the max parallelism, 0 is auto.
+    /// </summary>
     [JsonProperty("maxParallelism")]
     public int? MaxParallelism { get; set; }
 
+    /// <summary>
+    /// Set the parameters for markdown engine, value should be a JSON string.
+    /// </summary>
     [JsonProperty("markdownEngineProperties")]
     public MarkdownServiceProperties MarkdownEngineProperties { get; set; }
 
+    /// <summary>
+    /// Set the name of ICustomHrefGenerator derived class.
+    /// </summary>
     [JsonProperty("customLinkResolver")]
     public string CustomLinkResolver { get; set; }
 
+    /// <summary>
+    /// Define versions.
+    /// </summary>
+    [Obsolete("Use groups instead.")]
     [JsonProperty("versions")]
     public Dictionary<string, GroupConfig> Versions
     {
@@ -117,6 +221,20 @@ public Dictionary<string, GroupConfig> Versions
         }
     }
 
+    /// <summary>
+    /// Define groups.
+    /// </summary>
+    /// <example>
+    /// <code>
+    /// groups:{
+    ///   "v1": {
+    ///     "dest": "v1",
+    ///     "xrefTags: [],
+    ///     "extraMetadata01": {}
+    ///   }
+    /// }
+    /// </code>
+    /// </example>
     [JsonProperty("groups")]
     public Dictionary<string, GroupConfig> Groups
     {
@@ -132,12 +250,23 @@ public Dictionary<string, GroupConfig> Groups
 
     }
 
+    /// <summary>
+    /// If set to true, docfx does not dereference (aka. copy) file to the output folder.
+    /// Instead, it saves a link_to_path property inside manifest.json to indicate the physical location of that file.
+    /// </summary>
     [JsonProperty("keepFileLink")]
     public bool KeepFileLink { get; set; }
 
+    /// <summary>
+    /// Specifies the options for the sitemap.xml file.
+    /// </summary>
     [JsonProperty("sitemap")]
     public SitemapOptions SitemapOptions { get; set; }
 
+    /// <summary>
+    /// Disable fetching Git related information for articles.
+    /// By default it is enabled and may have side effect on performance when the repo is large.
+    /// </summary>
     [JsonProperty("disableGitFeatures")]
     public bool DisableGitFeatures { get; set; }
 }

src/Docfx.App/Config/ContentPairingInfo.cs

@@ -5,12 +5,21 @@
 
 namespace Docfx;
 
+/// <summary>
+/// Content pairing information used for <see cref="BuildJsonConfig.Pairing"/> options.
+/// </summary>
 [Serializable]
 internal class ContentPairingInfo
 {
+    /// <summary>
+    /// Content folder.
+    /// </summary>
     [JsonProperty("contentFolder")]
     public string ContentFolder { get; set; }
 
+    /// <summary>
+    /// Overwrite fragment files folder.
+    /// </summary>
     [JsonProperty("overwriteFragmentsFolder")]
     public string OverwriteFragmentsFolder { get; set; }
 }

src/Docfx.App/Config/FileMetadataPairs.cs

@@ -5,13 +5,21 @@
 
 namespace Docfx;
 
+/// <summary>
+/// FileMetadataPairs.
+/// </summary>
+/// <see cref="BuildJsonConfig.FileMetadata"/>
+/// <see cref="MergeJsonItemConfig.FileMetadata"/>
 [Serializable]
 [JsonConverter(typeof(FileMetadataPairsConverter))]
 internal class FileMetadataPairs
 {
     // Order matters, the latter one overrides the former one
     private List<FileMetadataPairsItem> _items;
 
+    /// <summary>
+    /// Gets FileMetadataPairs items.
+    /// </summary>
     public IReadOnlyList<FileMetadataPairsItem> Items
     {
         get
@@ -20,16 +28,25 @@ public IReadOnlyList<FileMetadataPairsItem> Items
         }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMetadataPairs"/> class.
+    /// </summary>
     public FileMetadataPairs(List<FileMetadataPairsItem> items)
     {
         _items = items;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMetadataPairs"/> class.
+    /// </summary>
     public FileMetadataPairs(FileMetadataPairsItem item)
     {
         _items = new List<FileMetadataPairsItem> { item };
     }
 
+    /// <summary>
+    /// Gets the element at the specified index.
+    /// </summary>
     public FileMetadataPairsItem this[int index]
     {
         get
@@ -38,6 +55,9 @@ public FileMetadataPairsItem this[int index]
         }
     }
 
+    /// <summary>
+    /// Gets the number of elements.
+    /// </summary>
     public int Count
     {
         get

src/Docfx.App/Config/FileMetadataPairsConverter.cs

@@ -8,13 +8,18 @@
 
 namespace Docfx;
 
+/// <summary>
+/// JsonConverter for FileMetadataPairs
+/// </summary>
 internal class FileMetadataPairsConverter : JsonConverter
 {
+    /// <inheritdoc/>
     public override bool CanConvert(Type objectType)
     {
         return objectType == typeof(FileMetadataPairs);
     }
 
+    /// <inheritdoc/>
     public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
     {
         var value = reader.Value;
@@ -27,6 +32,7 @@ public override object ReadJson(JsonReader reader, Type objectType, object exist
         return new FileMetadataPairs(jItems.Select(ParseItem).ToList());
     }
 
+    /// <inheritdoc/>
     public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
     {
         writer.WriteStartObject();

src/Docfx.App/Config/FileMetadataPairsItem.cs

@@ -6,16 +6,26 @@
 
 namespace Docfx;
 
+/// <summary>
+/// Glob/Value pair to define define file's metadata.
+/// </summary>
+/// <see cref="FileMetadataPairs"/>
 [Serializable]
 internal class FileMetadataPairsItem
 {
+    /// <summary>
+    /// The glob pattern to match the files.
+    /// </summary>
     public GlobMatcher Glob { get; }
 
     /// <summary>
     /// JObject, no need to transform it to object as the metadata value will not be used but only to be serialized
     /// </summary>
     public object Value { get; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMetadataPairsItem"/> class.
+    /// </summary>
     public FileMetadataPairsItem(string pattern, object value)
     {
         Glob = new GlobMatcher(pattern);