I’ve been updating one of my GitHub repositories (my Presentation.Core repo.) with some more documentation, using XML documentation comments, and thought I’d write a refresher post for taking your code from no documentation all the way through to being fully documented. <\/p>\n
<summary><\/strong><\/p>\n So the \/\/\/ is used for XML documenting comments in C#, for example<\/p>\n In the above, the <summary> element<\/a> (and it’s corresponding end element) within the \/\/\/ acts as a summary of our class. This class level summary is displayed in Visual Studio Intellisense when declaring a type of AsyncCommand<\/em> when we create code such as new AsyncCommand()<\/em> Intellisense will display the summary for the default constructor (if such documentation exists).<\/p>\n The summary tag is the most important tag for documenting our code using the XML documentation as it’ll acts as the primary source of information for Intellisense and within generated help files. <\/p>\n <remarks><\/strong><\/p>\n This is an optional documentation <remarks> element<\/a> which can be used to expand upon the summary or add supplementary documentation to the summary element. For example<\/p>\n Summary text is displayed by IntelliSense whereas Remarks are shown in the help file output via tools such as Sandcastle.<\/p>\n <returns><\/strong><\/p>\n As you might guess, the <returns> element<\/a> is used on method return values, for example<\/p>\n <param><\/strong><\/p>\n Continuing with the elements available for a method, the param element<\/a> is used for method arguments, to allow the documentation to list what each parameter is used for.<\/p>\n <value><\/strong><\/p>\n Like a return but used on a property, the <value> element<\/a> is used along with a summary to describe what the property represents.<\/p>\n <para><\/strong><\/p>\n The <para> element<\/a> is used within summary, remarks or return elements to add paragraph formatting\/structure to your documentation.<\/p>\n <exception><\/strong><\/p>\n The <exception> element<\/a> is used (as the name suggests) to list exceptions a method may throw during it’s execution. For example<\/p>\n IntelliSense will display the list of exceptions<\/p>\n <see><\/strong><\/p>\n The <see> element<\/a> allows us to reference documentation elsewhere within your code, it accepts a cref argument and within this we need to reference our classname.methodname etc. For example<\/p>\n Note: In the case of reference another method within the same class we need not declare the class name within the cref, but if referencing another class we should use classname.methodname syntax. <\/p>\n Within IntelliSense and documentation the full method name will be displayed for the see element’s cref.<\/p>\n <seealso><\/strong><\/p>\n Usage for <seealso><\/a> is as per the see element but generated code will create a see also section and place such references within.<\/p>\n <typeparam><\/strong><\/p>\n The <typeparam> element<\/a> is used to document the generic parameters passed to a class and\/or methods, for example<\/p>\n <paramref><\/strong><\/p>\n Used within a summary or remarks, the <paramref><\/a> is used to refer to a parameter on the method being documented. For example<\/p>\n In the above, generateFunc is displayed within the IntelliSense summary and highlighted (via an italic font) in generated help files.<\/p>\n <typeparamref><\/strong><\/p>\n Like paramref, the <typeparamref> element<\/a> can be used within summary, remarks etc. to link to a specific generic type, for example<\/p>\n As per paramref generated documentation may highlight the name within a help file and it’s also displayed via IntelliSense within the summary.<\/p>\n <list><\/strong><\/p>\n The <list> element<\/a> allows us to define formatted text in a bullet, name or table format within our summary block, for example<\/p>\n This results in generated documentation showing a bullet list of items, within IntelliSense, this isn’t quite so pretty and results in just the descriptions listed with space delimitation.<\/p>\n <example><\/strong><\/p>\n The <example> element<\/a> allows us to add example code to our documentation, for example<\/p>\n Note: Without the <code> element<\/a> the example is not formatted as we’d expected. This is results in a generated help file section named examples.<\/p>\n <code><\/strong><\/p>\n The <code> element<\/a> is used within the example element to format code samples. See above.<\/p>\n <c><\/strong><\/p>\n The <c> element<\/a> may be used within a summary or other element and formats the text within it as code. <\/p>\n <permission><\/strong><\/p>\n As you probably guessed, we can highlight the permissions expected or required for a method etc. using the <permission> element<\/a>. For example<\/p>\n The above will result in generated documentation with a security section which includes a table of the cref value and the description for the permissions required for the method.<\/p>\n\r\n\/\/\/ <summary>\r\n\/\/\/ A Task\/async aware command object. \r\n\/\/\/ <\/summary>\r\npublic class AsyncCommand : CommandCommon\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ A Task\/async aware command object. \r\n\/\/\/ <\/summary>\r\n\/\/\/ <remarks>\r\n\/\/\/ Automatically handles changes to the built-in, IsBusy flag, so when\r\n\/\/\/ the command is executing the IsBusy is true and when completed or not \r\n\/\/\/ executing IsBusy is false.\r\n\/\/\/ <\/remarks>\r\npublic class AsyncCommand : CommandCommon\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Implementation of CanExecute which returns a boolean\r\n\/\/\/ to allow the calling method to determine whether the\r\n\/\/\/ Execute method can be called\r\n\/\/\/ <\/summary>\r\n\/\/\/ <param name="parameter">An object is ignored in this implementation<\/param>\r\n\/\/\/ <returns>True if the command can be executed, otherwise False<\/returns>\r\npublic override bool CanExecute(object parameter)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Implementation of CanExecute which returns a boolean\r\n\/\/\/ to allow the calling method to determine whether the\r\n\/\/\/ Execute method can be called\r\n\/\/\/ <\/summary>\r\n\/\/\/ <param name="parameter">An object is ignored in this implementation<\/param>\r\n\/\/\/ <returns>True if the command can be executed, otherwise False<\/returns>\r\npublic override bool CanExecute(object parameter)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Constructor take a comparison function which expects two types of T and\r\n\/\/\/ returns an integer where a value less than 0 indicates the first item is \r\n\/\/\/ before the second, a value of 0 indicates they're equivalent \r\n\/\/\/ and a value greater than 0 indicates the first item is after\r\n\/\/\/ the second item. This constructor also takes a function for the object \r\n\/\/\/ hash code method.\r\n\/\/\/ <\/summary>\r\n\/\/\/ <param name="objectComparer">\r\n\/\/\/ A function to compare two items of type T\r\n\/\/\/ <\/param>\r\n\/\/\/ <exception cref="System.NullReferenceException">\r\n\/\/\/ Thrown when the objectComparer is null\r\n\/\/\/ <\/exception>\r\npublic ComparerImpl(\r\n Func<T, T, int> objectComparer)\r\n{\r\n _objectComparer = \r\n objectComparer ?? \r\n throw new NullReferenceException("Comparer cannot be null");\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Sets the property value against the property and raises\r\n\/\/\/ OnPropertyChanging, OnPropertyChanged etc. as required.\r\n\/\/\/ <see cref="GetProperty{T}"\/>\r\n\/\/\/ <\/summary>\r\nprotected bool SetProperty<T>(\r\n Func<T> getter, \r\n Func<T, T> setter, \r\n T value, \r\n [CallerMemberName] string propertyName = null)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Implements IComparer<T>, IEqualityComparer<T> \r\n\/\/\/ and IComparer\r\n\/\/\/ <\/summary>\r\n\/\/\/ <typeparam name="T">The type of being compared<\/typeparam>\r\npublic class ComparerImpl<T> : \r\n IComparer<T>, IEqualityComparer<T>, IComparer\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Gets the current value via a Func via the <paramref name="generateFunc"\/>\r\n\/\/\/ <\/summary>\r\n\/\/\/ <typeparam name="T">The property type<\/typeparam>\r\n\/\/\/ <param name="generateFunc">The function to create the return value<\/param>\r\n\/\/\/ <param name="propertyName">The name of the property<\/param>\r\n\/\/\/ <returns>The value of type T<\/returns>\r\nprotected T ReadOnlyProperty<T>(\r\n Func<T> generateFunc, \r\n [CallerMemberName] string propertyName = null)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Gets the current property value as type <typeparamref name="T"\/>\r\n\/\/\/ <\/summary>\r\nprotected T GetProperty<T>(\r\n Func<T> getter, \r\n Func<T, T> setter, \r\n [CallerMemberName] string propertyName = null)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Acts as a base class for view models, can be used\r\n\/\/\/ with backing fields or delegating getter\/setter \r\n\/\/\/ functionality to another class - useful for situations\r\n\/\/\/ where the underlying model is used directly\r\n\/\/\/ <list type="bullet">\r\n\/\/\/ <item><description>GetProperty<\/description><\/item>\r\n\/\/\/ <item><description>SetProperty<\/description><\/item>\r\n\/\/\/ <item><description>ReadOnlyProperty<\/description><\/item>\r\n\/\/\/ <\/list>\r\n\/\/\/ <\/summary>\r\npublic class ViewModelWithModel : ViewModelCommon\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Sets the property value against the property and raises\r\n\/\/\/ OnPropertyChanging, OnPropertyChanged etc. as required\r\n\/\/\/ <\/summary>\r\n\/\/\/ <example>\r\n\/\/\/ <code>\r\n\/\/\/ public string Name\r\n\/\/\/ {\r\n\/\/\/ set => SetProperty(value);\r\n\/\/\/ get => GetProperty();\r\n\/\/\/ }\r\n\/\/\/ <\/code>\r\n\/\/\/ <\/example>\r\nprotected bool SetProperty<T>(\r\n T value, \r\n [CallerMemberName] string propertyName = null)\r\n{\r\n}\r\n<\/pre>\n\r\n\/\/\/ <summary>\r\n\/\/\/ Gets the current property value\r\n\/\/\/ <\/summary>\r\n\/\/\/ <permission cref="System.Security.PermissionSet">\r\n\/\/\/ Unlimited access to this method.\r\n\/\/\/ <\/permission>\r\nprotected T GetProperty<T>([CallerMemberName] string propertyName = null)\r\n{\r\n}\r\n<\/pre>\n