Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doc comments to docfx.json related config files. #8969

Merged
merged 8 commits into from
Jul 17, 2023

Conversation

filzrev
Copy link
Contributor

@filzrev filzrev commented Jul 15, 2023

This PR add doc comments that are related to docfx.json configs.
and adding some obsolete attributes.

Purpose of this PR
Preparation to create JSON schema document for docfx.json from C# code and doc comments. (#8968)

Add Obsolete attribute
This PR add `[Obsolete] property to following properties

Documentation comments
Almost doc comments are taken from following contents.

Some properties are not documented. and no working example found.
So I've added doc comment these property.

** List of undocumented build section properties**

Name Used for what's purpose
pairing Used for overwrite folder mappings.
xrefTags Not used in docfx. It's simply exported to xrefmap.yml
tagParameters SchemaDrivenDocumentProcessor handle tags but no usage examples found.
versions It seems deprecated. replaced by groups.
'groups' Used for grouping content/resource files

@codecov
Copy link

codecov bot commented Jul 15, 2023

Codecov Report

Patch coverage has no change and project coverage change: +0.03 🎉

Comparison is base (8f411e0) 76.88% compared to head (2a40b8c) 76.92%.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8969      +/-   ##
==========================================
+ Coverage   76.88%   76.92%   +0.03%     
==========================================
  Files         605      605              
  Lines       25074    25054      -20     
==========================================
- Hits        19279    19272       -7     
+ Misses       5795     5782      -13     
Impacted Files Coverage Δ
src/Docfx.App/Config/BuildJsonConfig.cs 86.11% <ø> (ø)
src/Docfx.App/Config/ContentPairingInfo.cs 0.00% <ø> (ø)
src/Docfx.App/Config/FileMetadataPairs.cs 66.66% <ø> (ø)
src/Docfx.App/Config/FileMetadataPairsConverter.cs 83.33% <ø> (ø)
src/Docfx.App/Config/FileMetadataPairsItem.cs 100.00% <ø> (ø)
src/Docfx.App/Config/GroupConfig.cs 0.00% <ø> (ø)
src/Docfx.App/Config/ListWithStringFallback.cs 100.00% <ø> (ø)
...ocfx.App/Config/ListWithStringFallbackConverter.cs 40.00% <ø> (ø)
src/Docfx.App/Config/MergeJsonConfig.cs 0.00% <ø> (ø)
src/Docfx.App/Config/MergeJsonConfigConverter.cs 0.00% <ø> (ø)
... and 9 more

... and 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

src/Docfx.App/Config/BuildJsonConfig.cs Show resolved Hide resolved
src/Docfx.App/Config/BuildJsonConfig.cs Outdated Show resolved Hide resolved
src/Docfx.App/Config/BuildJsonConfig.cs Outdated Show resolved Hide resolved
@filzrev
Copy link
Contributor Author

filzrev commented Jul 16, 2023

I've fixed commented issues with following commits.

  • Fix XRefMaps comments (5b9936c)
  • Add obsolete attributes to pairning and tagParameters and fix doc comments.
    (1d746e9)

That http/https check is in DocumentBuildContext.LoadXRefMap, which is called by LoadXRefMaps,
but does anything call LoadXRefMaps…? It seems these methods are no longer used and
the real code is in class XRefMapDownloader...

It seems there are some unused code exists.
I'll create another PR to fix this problems.

@filzrev
Copy link
Contributor Author

filzrev commented Jul 17, 2023

Add commit (2a40b8c)
to fix problem that .gitignore file created by docfx init command don't contains _site entry .

@yufeih yufeih merged commit 4ead6e2 into dotnet:main Jul 17, 2023
@yufeih yufeih added the new-feature Makes the pull request to appear in "New Features" section of the next release note label Jul 17, 2023
p-kostov pushed a commit to ErpNetDocs/docfx that referenced this pull request Jun 28, 2024
* 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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
new-feature Makes the pull request to appear in "New Features" section of the next release note
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants