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

Make Triple Slash Comments Source of Truth #12262

Open
lonitra opened this issue Oct 2, 2024 · 3 comments
Open

Make Triple Slash Comments Source of Truth #12262

lonitra opened this issue Oct 2, 2024 · 3 comments
Assignees
Milestone

Comments

@lonitra
Copy link
Member

lonitra commented Oct 2, 2024

Currently we need to manually port any new documentation to the dotnet-api-docs repo when it comes time to documenting new APIs that have been added in the release cycle. We should investigate making our source code documentation the source of truth so that we reduce the manual effort that occurs when it comes time to documenting new APIs for the release cycle.

In runtime repo, this has already been achieved for some projects by creating a transport package that automatically pushes the ref assemblies and the intellisense files to a feed where the dotnet-api-docs repo consumes that package to update the Microsoft Learn website.

@lonitra lonitra added this to the .NET 10.0 milestone Oct 2, 2024
@lonitra lonitra self-assigned this Oct 2, 2024
@RussKie
Copy link
Member

RussKie commented Oct 4, 2024

This item has been long on a backlog with some progress. It is hard to tell from the issue whether it is something you've already figured out or you're just planning to.

Essentially, Microsoft.Private.Winforms is the package that contains triple-slash docs, which are ingested by the docs system. However, when I worked on this, the docs system would only ingest the new docs and won't update any of the existing. To make the code the source of truth, we'd need to import all existing triple-slash docs from the docs system. That was meant to be achievable by the DocPorting tool which @jeffhandley and @carlossanlop worked on.
Once all the existing triple-slash docs are imported into the codebase, the docs system will need to be reconfigured to ingest all incoming docs from the source.

Back in the days, with the docs team we discussed possibilities of creating two flows: source->docs and docs->source, but I don't know whether this story had any progress since then.

@lonitra
Copy link
Member Author

lonitra commented Oct 7, 2024

This was just a plan. I was not aware that this already had some progress to it so thank you! Is there an issue that captures this and history of the progress thats been made so I can catch up?

@RussKie
Copy link
Member

RussKie commented Oct 8, 2024

I think it's how it always worked - this repo bundles xmls into Microsoft.Private.Winforms, and the Docs system ingest those... ¯\_(ツ)_/¯

Whenever there were missing docs, @carlossanlop would come here and shame us, and we'd fix the gaps either by updating the source or updating the xmls at https://github.com/dotnet/dotnet-api-docs/ (e.g., dotnet/dotnet-api-docs#7114).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants