Hiding Classes/Methods From XML Documentation - c#

I have a number of interfaces in an assembly which I need to document using XML-Doc and Sandcastle. However, there are also a few interfaces I would like to ignore when building the documentation file. Right now I manage to do it by compiling the assembly with those interfaces marked as internal, but this is more a workaround than a solution to the problem since, in fact, those need to be public. Is there some kind of attribute one can decoracte unwanted ones with so that they are ignored?

I think the only way to hide specific types/members from IntelliSense is to set their access modifier as you mention you currently do.
As far as doing this with Sandcastle, you can use API filters similar to what is discussed in this MSDN blog post.

Related

Should I reuse Microsoft.NET attributes for other reasons or should I create my own attributes?

Is it appropriate to use the attributes that Microsoft.NET provides for alternative uses or should I create my own attributes?
For example, I've often seen people use the DescriptionAttribute for enumerations as "friendly names". Though, my understanding was that the DescriptionAttribute was intended to be used by the IDE and for this reason.
Another example would be to use the DefaultAttribute to, through reflection, set all of the default values of properties during construction.
So, is it acceptable within best practices to reuse attributes in ways not normally intended?
Personally, I don't re-use attributes. I create my own custom ones.
This prevents me from using attributes and then getting unexpected behavior in the future when somebody uses my classes in a way that I didn't anticipate.
the DefaultAttribute and DescriptionAttribute are used by the "propertygrid" control, which is the control used in the visual studio designer. it is also possible to use this control in your own code, and then it makes sense using these attributes
Use the definition MS provide, and create your own when they don't fit the official definition. Might sound silly to create your own (not that it's really long to create a new one), but if someone come to read your code and didn't read the 20 pages manual intitled "our alternative uses of official attributes", he will be all confused about what's going on.
Beside, lot of .NET classes check for those attributes. You can end up with very weird behavior if you misuse them.
Microsoft's own posted best practices have nothing to say on the subject, and the code usage on the DescriptionAttribute MSDN Page makes it clear that this built-in attribute is used in some other ways. I would generally consider it very dangerous to add extra meaning to something that only has relevance in your project. This is referred to as 'tribal knowledge' and is one of the major ways misunderstandings start when working with others.
If you have a use-case that is covered by the .NET framework, awesome - you should definitely use what's out there first. But if you're not sure, it is probably best to simply create your own.

Hide class members from everything except another specific assembly

I have two class libraries "MyLibrary.dll" and "MyLibraryEditor.dll" for a Unity runtime and editor extension. There are several class members inside "MyLibrary.dll" that are only intended for use by "MyLibraryEditor.dll".
My first thought was to use the internal keyword because I mistakenly thought that this constrained visibility to a namespace. Instead it is clear that this keyword limits visibility to the assembly.
What is the best way to constrain access to some class members to "MyLibrary.dll" and "MyLibraryEditor.dll" without hurting performance? Also, reflection is not an option.
I am happy to simply not document the functions, but unfortunately Intellisense (and MonoDevelop's equivalent) show these members.
If you want internals in one assembly to be visible from another assembly, you can use the InternalsVisibleTo attribute on the assembly containing the internals. See http://msdn.microsoft.com/en-us/library/system.runtime.compilerservices.internalsvisibletoattribute.aspx:
[assembly:InternalsVisibleTo("MyLibraryEditor")]
That answered, you might want to rethink your architectural design so that you don't need to use it, since it will open up all internals to the other assembly, not only the ones that you want.
You could make the members internal but use [InternalsVisibleTo] to give access to those members to the other assembly. They'd still be visible within the same assembly as well, of course... there's no way of getting round that.
I primarily use InternalsVisibleToAttribute for giving access to internal members to test classes, and would try to avoid doing this for non-test purposes - but sometimes it can be useful.
This is not possible using pure C# concepts. You are two seperate assemblies, that is as far seperate as you can get, and there is no relationship between the two as far as .Net is concerned.
you could do some things with signing or validation to make it so it would be difficult to use one assembly without the other, but not something you can do to prevent visibility of the classes/members.

can csharp classes "inherit" the xml documentation like java classes can?

i'm adding comments to some csharp code, and i'm using the xml language provided by .net (or something). i have an interface, and some implementing classes. i have one method in the interface, and it has a comment. in the implementing classes there is no comment on the implementing method.
when one does it like this in java, javadoc automagically uses the interface comment when generating documentation. however, now that i build my project, i get the warning (transalted from swedish, sorry) "the xml comment for the visible type or member bla.blabla.blablabla() is missing (cs1591)". this is only a warning, so not so bad. but!!! it means no xml file was output, so i can't use sandcastle to generate a chm document file, which is my real goal here.... googling the error coded gave nothing :(
do i really have to copy the method comment to all implementing classes? that's like.... code duplication D: is there no way to get the behavior java offers?
I don't know of any way of getting it to happen at XML file generation time, but GhostDoc may well save you from performing the copying manually. I can't say I've used it myself though.
I agree that it would be a valuable feature... particularly if the base class (or interface) documentation changes after the derived classes have been implemented and documented.
You do have to copy the interfaces comments to the implementing class. Generally this is a good thing as the two comments should ideally be different - my opinion (and practise) on this can be summarised as the following:
Interface Comments - Explains what the method/property/etc is supposed/expected to do but should generally not proscribe how any specific implementation should behave
Implementing Class Comments - Explains what the method/property/etc actually does and may include some details of how this is done (typically in <remarks>)
VSdocman can resolve missing XML comments from implemented interfaces automatically when it generates documentation. Moreover, like GhostDoc, it can also explicitly copy inherited comments to the implementing method. Unlike Sandcastle, it's not free.
Well i dont know about Java but Sorry you will have to copy the interface's comments in the implemented class. here is no inbuilt way of doing it...
And yeah consider the suggestion given by JonSkeet

Why same dll exposes different classes in C# and .net

I am using a third party .Net dll in my code and when I add a reference to this dll from a VB.Net application it shows different classes in intellisense and object browser than when I use it in a C# project. Why is there this difference?
Edit
If designer intended it that way I'd like to know how to do it in my own dlls.
Without knowing the specifics, it is hard to say. Some possibilities that come to mind are:
The designer made it that way on purpose
Parts of the library are not CLR compliant, and therefore not visible by languages other than the one it was written in.
VB.NET provides the option to "hide advanced members". Perhaps it's the "advanced" members you're not seeing.
One thing to remember here is that intellisense is an approximation of what's allowed and legal in the program. It's goal is to be very close to true but often isn't. There are several reasons why a particular type may or may not show up in intellisense but does in C#
One of the 2 projects may be friends with the target assembly
Intellisense filters may exist on the documentation files which hide them from intellisense
Attribute filters on the type
Certain classes may get hidden due to case only differences in the name
Given that it also doesn't show up in the object browser, my guess is that the class has either intellisense or attribute filters that cause it to be hidden for VB.Net.

Prevent other developers using base methods within a class

I have a class that uses filesystem entities to manipulate data. We have several methods specifically designed to (attempt to) cope with some of the issues we face with this approach (file locking, non-existent files, etc.). Ideally I'd like to be able to issue a warning if another developer attempts access the filesystem directly via System.IO rather than using the helper methods.
Is this possible? The behaviour I'm looking for is to effectively mark methods such as File.ReadAllText() as if they were obsolete, but only within this project (NOT solution-wide).
I've done some digging around, and it looks like my only option is "tell them to make sure they use your methods". I'm hoping someone can give me a different, and more helpful answer. :)
--EDIT--
The suggestions of a custom StyleCop or FxCop rule are good, but unfortunately impractical in this scenario (not every developer in the department uses these excellent tools), and the legitimate methods that do the file access do use System.IO. Adding "ignore" attributes to the legit methods is a dangerous idea, too. If someone sees how I've "broken" my own rule, they'll likely copy the attribute to their own method.
Use a static analysis tool (such as StyleCop or FxCop) with a rule that captures "Do not use System.IO directly." Then integrate it as part of your automated build process and throw up if someone does try to use System.IO directly. No one likes to break the build.
You can write custom analysis rule for FxCop/Visual Studio Code Analysis and run these as part of your automated build.
Hmm. Not tried this myself, but how about forcing people to use your custom file handling classes, by using a namespace alias that "hides" the genuine System.IO. If I remember rightly these are applied at a project level.
Not sure if either of these suggestions are valid as I've never done them, but some food for thought:
Isn't this what "Enterprise Templates" are designed for? Don't they allow you to craft a policy file that restricts the allowed project references?
Alternatively, while not foolproof, could you add a pre-build event to the project that throws a warning if System.IO is referenced?
Can you add some custom functionality to a source-control commit hook? It won't find existing violations (if there are any) unless those files are changed but should detect new uses?
Any good?

Categories

Resources