Feature Request: Resolve Missing XML For Public Type Warnings

[AristurtleDev]

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

1. Ensures that intellisense is provided for all public types when using MonoGame
2. Ensure that all public types have API Reference documentation generated for the website.

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 branch

https://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.

© 2012 Microsoft Corporation. All rights reserved.

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:

1. Given that Microsoft provided this documentation to the MonoGame foundation, it may not be available to distribute publicly to community members to contribute to this feature. This has been discussed already in the MonoGame discord and I believe the current recommendation is to provide a private repo and have contributing members sign an NDA ^[2]
2. Where should the copyright text be placed? @tomspilman has suggested placing it in the footer of the website along with the MonoGame copyright^[3]. This would satisfy the requirement for the website presence but do we need to also include the copyright information in the source code as well? For instance

/// <summary>
/// Example documentation that might have been provided by microsoft
/// <summary>
/// © 2012 Microsoft Corporation. All rights reserved.

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:

• Microsoft permission to use XNA documentation ^[1]
• Discord discussion on potential private repo and NDA for access ^[2]
• Tom recommends adding copyright to website footer ^[3]
• Community member asking about SamplerState API reference documentation ^[4]

[Brett208]

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

[mrhelmut]

Thank you for proposing!

Tom is working on the onboarding process. Once setup, we'll be able to welcome contributions.

[AristurtleDev]

@mrhelmut
cc: @Maniekko @dellis1972 @tomspilman

while working through some of this, I'm noticing some documentation language that might need to be updated. For instance, several of the == operator overload methods in the original XNA documentation just state the same thing

Compares the current instance of a class to another instance to determine whether they are the same.

(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 struct not class members. A more modern summary text would be something like

Returns a value that indicates whether two [explicit-type-name] are equal

where [explicit-type-name] is the type name like Bgr565

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?

[dellis1972]

@AristurtleDev I'm ok with updating to use the new language.