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
Feature Request: Resolve Missing XML For Public Type Warnings #8165
Comments
Routinely I find myself wishing documentation for MonoGame was more available via intellisense, so would much appreciate this task happening. I am willing to provide identification, sign an NDA, etc. to complete the grunt work of moving the XML documentation over if it would be helpful. -Brett |
Thank you for proposing! Tom is working on the onboarding process. Once setup, we'll be able to welcome contributions. |
@mrhelmut while working through some of this, I'm noticing some documentation language that might need to be updated. For instance, several of the
(source: https://learn.microsoft.com/en-us/previous-versions/windows/xna/bb196576(v=xnagamestudio.42)) However, this summary text isn't correct. For instance, most of these are
where In these instances, would it be preferred to just use the original XNA documentation, or would it be ok to update the text to match a more modern summary? |
@AristurtleDev I'm ok with updating to use the new language. |
Description
This is a feature request to have the source code updated so that all publicly visible types contain XML code documentation. This serves two purposes
Currently when building MonoGame from source, there are approximately 861 warnings issues due to missing XML documentation in code. Here is a spreadsheet for reference from a current build of the
develop
branchhttps://docs.google.com/spreadsheets/d/1CMKClYiAuwbw1M7vMwqQFRj-Loq6a7VmTpqbb1HiNTE/edit?usp=sharing
Based on discussion from #7693, Microsoft has given permission and provided access to the original XNA API reference that can be used to fill in the missing XML code documentation in the source [1] as long as the following copyright text is included.
Implementation
My suggested implementation of this is to take the XNA API reference documentation provided by Microsoft and use that to complete the missing XML code documentation in the MonoGame source code. However, in doing this, a few questions are posed:
These are the two questions I can think of at the moment, but I'm sure there are more. Regardless, to ensure we remain in legal compliance with the supplied documentation provided by Microsoft, guidelines and a process will need to be established.
Motivation
There are times when the question is asked in the community discord and forums about where to find API reference documentation that is missing [4]. Currently we have to point these questions to the MSDN site where the original XNA API reference exists. However, there is no guarantee that Microsoft will keep these pages available.
References:
The text was updated successfully, but these errors were encountered: