CODEWITHSUNDEEP
c#visual-studio-2010documentationapplication-settings
Len
Len

Reputation: 2145

Documenting (XML) Application Settings in Visual Studio 2010

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?

I'm using Sandcastle Help File Builder by the way

Upvotes: 7

Views: 3076

Answers (3)

laurian
laurian

Reputation: 809

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.

Upvotes: 2

veselka
veselka

Reputation: 132

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.

Upvotes: 10

Len
Len

Reputation: 2145

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.

Upvotes: 0

Related Questions