More documentation

git-svn-id: file:///srv/devel/repo-conversion/nusu@325 d2e56fa2-650e-0410-a79f-9358c0239efd
This commit is contained in:
Markus Ewald 2014-07-24 16:04:09 +00:00
parent 3a945f5d48
commit ab6a3374d8
2 changed files with 79 additions and 2 deletions

View File

@ -28,8 +28,67 @@ namespace Nuclex.Support.Settings {
/// <summary>Represents an ini- or cfg-like configuration file</summary> /// <summary>Represents an ini- or cfg-like configuration file</summary>
/// <remarks> /// <remarks>
/// <para>
/// This class tries its best to preserve the formatting of configuration files. /// This class tries its best to preserve the formatting of configuration files.
/// Changing a value will keep the line it appears in intact. /// Changing a value will keep the line it appears in intact. The parser also takes
/// as much data from a line as it can - anything to the left of an equals sign
/// becomes the name, anything to the right (excluding comments) becomes the value.
/// </para>
/// <para>
/// To access the contents of a configuration file, simply parse it and use it like
/// you would any other settings store:
/// </para>
/// <example>
/// <code>
/// // # Settings.ini
/// // message = hello world ; the usual...
/// // show message = true
/// ISettingsStore settings;
/// using(var reader = new StreamReader("settings.ini")) {
/// settings = ConfigurationFile.Parse(reader);
/// }
///
/// if(settings.Get&lt;bool&gt;(null, "show message")) {
/// Console.WriteLine(settings.Get&lt;string&gt;(null, "message"));
/// }
/// </code>
/// </example>
/// <para>
/// It's usually a good idea to keep an application and all of its required files
/// together, whether it's code or data, but platforms often have their own conventions:
/// </para>
/// <list type="bullet">
/// <listheader>
/// <term>Operating System</term>
/// <description>Convention</description>
/// </listheader>
/// <item>
/// <term>Linux</term>
/// <description>
/// System-wide configuration goes into /etc/&lt;appname&gt;/, user-specific
/// configuration goes into ~/.&lt;appname&gt;/ while static configuration that is
/// known at build time resides with the application in /opt/&lt;appname&gt;/
/// </description>
/// </item>
/// <item>
/// <term>Windows</term>
/// <description>
/// System-wide configuration goes into %ProgramData%, user-specific configuration
/// has no real place (try %AppData%/&lt;appname&gt;/ if you want to hide it from
/// the user, %UserProfile%/Documents/&lt;appname&gt; if the user should see it)
/// and static configuration resides with your application
/// in %ProgramFiles%/&lt;appname&gt;/.
/// </description>
/// </item>
/// <item>
/// <term>MacOS</term>
/// <description>
/// System-wide configuration goes into /etc/&lt;appname&gt;/, user-specific
/// configuration goes into /Users/&lt;username&gt;/.&lt;appname&gt;/ while static
/// configuration resides with the application in /Applications/&lt;appname&gt;/
/// </description>
/// </item>
/// </list>
/// </remarks> /// </remarks>
public partial class ConfigurationFileStore : ISettingsStore { public partial class ConfigurationFileStore : ISettingsStore {

View File

@ -29,6 +29,24 @@ using Microsoft.Win32;
namespace Nuclex.Support.Settings { namespace Nuclex.Support.Settings {
/// <summary>Stores settings in the registry on Windows operating systems</summary> /// <summary>Stores settings in the registry on Windows operating systems</summary>
/// <remarks>
/// <para>
/// For the cases when you must use the Windows registry, the windows registry store
/// lets you map a registry key as a settings store. Its direct subkeys will become
/// categories and all registry values are made available as options.
/// </para>
/// <para>
/// Use of the registry is strongly discouraged. It binds you to Microsoft's silly
/// technology stack and fragments your application by storing some of its data in
/// the file system while storing other data in an opaque, globally-shared settings
/// manager that is filled with megabytes on unrelated things. Xcopy deployment
/// and portability will be out of the question when relying on the registry.
/// </para>
/// <para>
/// Instead of using this, consider querying for the platform's appropriate location
/// to store settings in.
/// </para>
/// </remarks>
public class WindowsRegistryStore : ISettingsStore, IDisposable { public class WindowsRegistryStore : ISettingsStore, IDisposable {
/// <summary>Initializes a new settings store on the specified registry path</summary> /// <summary>Initializes a new settings store on the specified registry path</summary>