I hate documentation that does nothing but repeat verbatim what can already easily be deduced from the syntax. I mean, how often have I see a property called "Foo" with the description "Gets or sets the value of Foo.". This is plainly idiotic. This documentation won't help me at all if I don't know what "Foo" is used for, what values it admits, and whether there's lots of it on the moon.
So can't Microsoft's writers do better than this example?
From: System.Configuration.SectionInformation.ProtectionProvider
The following example shows how to get the ProtectSection value of a ConfigurationSection object.
C#
static public void GetProtectionProvider() { SectionInformation sInfo = GetSectionInformation(); ProtectedConfigurationProvider pp = sInfo.ProtectionProvider; if (pp == null) Console.WriteLine("Protection provider is null"); else Console.WriteLine("Protection provider: {0}", pp.ToString()); }
Thank you very much. Your attention to detail in providing me with 100% example coverage in the documentation has been most enlightening. Fortunately I was just casually browsing through the Configuration API so I don't actually care about the ProtectionProvider property. In any case, I'm pretty sure I could figure out what to do with it. And if in doubt, I can always whip out Reflector. That's an especially useful trick with such programmer-friendly management-approved frameworks as ASP.Net.
P.S. Microsoft is by no means the only offender here!
No comments:
Post a Comment