craftworkgames
[Documentation] Some built-in comments
Not a critical addition, but I think utilizing the XML comments for some of the classes, methods, properties, etc would really help people get the hang of MG.E a lot quicker, and make thing more accessible overall. It's a lot easier to hover over an element in VS and check the full documentation if you need more insight than to have to go to the doc files every time you want to double-check what something does. A quality-of-life feature for sure, but not a hard thing to do; even just taking snippets from the full docs would be a huge time-save.
Some of the code has XML comments.
It's quite a big job going through all of the classes and commenting everything with actual useful comments. Personally I don't find comments very useful if they just describe what can already be seen from the code itself. For example, here's a random one I just found:
/// <summary>
/// Implements the operator ==.
/// </summary>
/// <param name="x">The lvalue.</param>
/// <param name="y">The rvalue.</param>
/// <returns>
/// <c>true</c> if the lvalue <see cref="HslColor" /> is equal to the rvalue; otherwise, <c>false</c>.
/// </returns>
public static bool operator ==(HslColor x, HslColor y)
That's 8 lines of XML that literally adds no value to the code. Personally, I find these kinds of comments to just clutter up the code. Luckily, I found a Visual Studio Extension called NoComment to hide them most of the time :)
That said, many of the XML comments are actually useful. So I'm in favor of having them if they are written with some thought.
We accept pull requests ;)
It would be great to add comments to a library. Although most of the time they might have little value, when they have, they also make it easier to use it and do not require going to the source code all the time when it is not obvious what the property does.
