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

Orfield

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.

Sclerenchyma

Im not able to check it out, but thanks. This question was posted a long while a go, but will try it in the future. Thanks – Orfield

I'm also not able to find it. But I think what you say is "Resources", which is different from settings. – Neoterism

Just wanted to point out that you'll have to select the setting in question to edit its description from the properties window. – Carrew

Another explanation: Select the table line with a specific setting => press F4 (usually) to open the properties window => field "Description". – However, I would like the table itself having a column "Description". – Menagerie

Answer 2

In your Settings.settings file (don't open it with the designer), add an attribute, e.g. "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.

Idiomorphic

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.

Orfield