Documenting (XML) Application Settings in Visual Studio 2010

Question

I recently created a (C#) project with Visual Studio (2010) and used some Settings (which I created under Properties).

The only place I found where I can add some XML comments for my documentation, would be in Settings.Designer.cs. However this file is auto-generated so whenever I change the Settings, the comments are gone.

Even Visual Studio gives started giving mewarnings, "Missing XML comment for publicity visibly type or member .... "

My question here is: What is the neatest way to add XML comments to my Settings?

• Is there a better place than Settings.Designer.cs?
• Should I stop the file from being auto-generated? How?
• Any other way?

I'm using Sandcastle Help File Builder by the way

Answer 1

If you open your settings (using default designer), you can find in properties window property "Description". Fill it in and it will be used as XML comment summary in autogenerated file.

Answer 2

In your Settings.settings file (don't open it with the designer), add an attribute, eg "Description":

<Setting Name="MySetting" Description="This property does blah blah blah" Type="System.Int32" Scope="Application">
  <Value Profile="(Default)">42</Value>
</Setting>

This will generate

/// <summary>
/// This property does blah blah blah
/// </summary>
[global...]
public int MySetting { ...

You can also build a tool that takes the Settings.settings file and create an MAML topic file. Call the tool in your project's build event and voilà.

In my tests, if you put the description as an attribute of the Setting element, it will be kept if you change the setting in the designer, the attribute will be kept. However, if you put it as a child of the Setting element, it will be deleted.

Answer 3

Did it. I'm still not sure if there is a better way, but i added a SettingsDoc.xml to my Sandcastle HFB project. disadvantage is that it doesnt get compiled by visual studio, so I need to update and check references etc myself.