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
Related
Trying to get my mind around google protobuf. I found some implementation of protobuf in C# but they seems to lack one feature: the ability to generate .proto files automatically from an existing C# class decorated with attributes.
The reason I want to do it this way instead of going from auto-generated C# classes from .proto file is because I already have the C# classes defined in my project and I don't want to duplicate them just to satisfy ProtoBuf.
Does anyone have encountered such a scenario?
Update
Is this possible to just decorate a C# class and not use a .proto file to use protobuf?
Good news; what you have described (having existing C# classes) is the expected use-case of protobuf-net. All the .proto stuff ("protogen", the VS add-in, etc) were all added as afterthoughts. The core of protobuf-net doesn't know about them or care about them.
protocol buffers defines a DSL (.proto, as you mention) that is shared between implementations, and is (sometimes) used for code generation. When I first wrote protobuf-net, the code-generation aspect wasn't my biggest concern - simply that .NET developers are generally guilty (myself included) of "implementation first" rather than "contract first".
As a consequence, protobuf-net doesn't need .proto files to work; an attributed class is sufficient to unambiguously serialize/deserialize. Just use Serializer.Serialize , .Merge and .Deserialize (etc).
That said; it does include some very under-developed and experimental support for this:
string proto = Serializer.GetProto<YourType>();
This is far from complete, but may work for simple types. If you have some specific cases where it fails, then let me know (add a comment or log an issue). However; most of the time, people interested in .proto would write the .proto first and work from there.
Examples of working decorated types are shown on the project home page; it is entirely up to you whether you use WCF attributes, xml attributes or protobuf-net attributes (although the latter provide more control over some specific serialization points, such as inheritance and numeric layouts).
Before Skeet Marc runs in here and gets massive ups, let me point out protobuf.net.
I want to add some methods in System.Net.HttpWebRequest class to suit my needs. I tried reflection but it is quite complicated that I need to alter many of its member class method as well.
I am debugging through .NET reference source and I could view the source code of those class. Is it possible for me to copy each of the related class source code and build my own class?
For some classes yes, but for many no.
.NET classes frequently use internal classes that are not exposed publicly, you would not only need to rebuild the class you are interested in but also rebuild all internal references too.
I would recommend not trying to do this and instead either using Extension Methods or if that does not solve your problem ask a new question describing the exact thing you are trying to accomplish and perhaps we can show you a easier way to do it.
Anything's possible.
You have the source code. You know how to copy and paste. Certainly it's possible you could adapt that code for your own purposes.
The question is; is it legal?
To answer that, you need only examine the license for the reference source. To that end, it's perfectly legal, assuming you comply with the MIT license (which is pretty lenient).
The next question is; should you? Probably not. Most likely, you could just add your desired functionality via a helper class or child class, or add new methods via Extension Methods.
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.
While I think I understand why inline XML documentation (i.e. using three slashes - ///) isn't working for me, I'd like to get some guidance on how to work around my "problem".
I have an interface, and two derived classes. One derived class is for simulation, and the other is for talking to real hardware.
It's very likely that the hardware implementation would do something special that the simulator doesn't need to do. I have XML documentation for the hardware methods, and not for the simulator. However, when I hover over the method name, I don't get documentation in the tooltip at all, presumably because the XML docs aren't associated with the interface.
This certainly makes sense, and I plan to just put my documentation in the interface instead and live with it. I am still curious, though... how does everyone else do this? Is there some magical way to make the tooltip aggregate all of the valid XML docs? In other words, since the compiler doesn't know which derived class is being used, is there a way for it to show XML docs for all classes that implement this interface?
This won't solve all your problems but GhostDoc can quickly insert documentation into a derived class using the base class documentation. It's worth taking a look anyway if you're doing XML documentation.
Since you are programming to an interface, there is not a way to pass through the XML documentation from the implementation. The separation means that the two "sides" don't know about each other. Like you said, you could have two different implementations of that interface. In that case, you would have a conflict. That isn't a big deal for two, but what about 200? Besides, the point of using an interface is that you don't care how it is implemented. You know that when you call use an interface, the implementation will follow the contract. Use the XML comments on the interface to describe the contract, not the implementation of the contract.
I can feel your pain on this one and I'm not sure that there is a better solution.
I have created a schema as an agreed upon interface between our company and an external company. I am now creating a WCF C# web service to handle the interface.
I ran the XSD utility and it created a C# class. The schema was built in BizTalk, and references other schemas, so all-in-all there are over 15 classes being generated.
I put [DataContract} attribute in front of each of the classes.
Do I have to put the [DataMember] attribute on every single property?
When I generate a test client program, the proxy does not have any code for any of these 15 classes.
We used to use this technique when using .asmx services, but not sure if it will work the same with WCF. If we change the schema, we would want to regenerate the WCF class, and then we would haev to each time redecorate it with all the [DataMember] attributes? Is there an newer tool similar to XSD.exe that will work better with WCF?
Thanks,
Neal Walters
SOLUTION (buried in one of Saunders answer/comments):
Add the XmlSerializerFormat to the Interface definition:
[OperationContract]
[XmlSerializerFormat] // ADD THIS LINE
Transaction SubmitTransaction(Transaction transactionIn);
Two notes:
1) After I did this, I saw a lot more .xsds in the my proxy (Service Reference) test client program, but I didn't see the new classes in my intellisense.
2) For some reason, until I did a build on the project, I didn't get all the classes in the intellisense (not sure why).
Neal, besides all the options John has given you, you should also check out the WCSF.blue tool on Codeplex: http://wscfblue.codeplex.com/
It's a "contract first" approach to doing WCF, and one of the many options it offers is to create a WCF DataContract file from your XSD:
This then pops up a dialog in which you can set a slew of parameters on how to create your C# class file from the XSD:
Quite useful, even if you want to use it for nothing more than converting XSD to C# classes that work as WCF DataContracts :-)
Also see this blog post for more explanations on the XSD DataContract generation process.
Classes that use [DataContract] will serialize to a very limited schema. For instance, there will be no attributes, only elements. This is intentional, and is done for performance and interoperability.
In general, a schema of the kind you may be working with may be much more complicated. Such a schema will not be usable with the Data Contract Serializer. You will need to use the XML Serializer instead.
In particular, don't edit the classes created by XSD.EXE. In fact, you should never edit generated code, as your edits will be removed as soon as the code is generated again. These classes should already have the attributes on them that will be needed for WCF to work with them.
What happens if you just use them as-is?
I'm shocked that no one pointed me to this utility, which I believe is what I was asking for:
http://msdn.microsoft.com/en-us/library/system.runtime.serialization.xsddatacontractimporter.aspx
I haven't tried it yet, but it looks like XsdDataContractImporter was what I was looking for, or the SVCUTIL with the /dataContractOnly flag.
I learned this when interviewing a candidate yesterday. She said DataContract serialization is faster and would be preferred to use.
Neal
Re: your XsdDataContract class mentioned in your followup, IMO, This is a niche class (as is ServiceContractGenerator etc) so i'm not surprised no one pointed you to it.
You still need to package it up to make it really useful. I'm pretty sure that code sample covers only very basic use cases so I would expect to do a lot of work with that to get it to a proper working state. . And like i mentioned on the WSCF forum, Svcutil, wscf, xsd.exe and others all use this class and related classes in the code gen process.
Regards the serializer performance, there are really good posts on Youssef Moussaoui's blog on the different serializers and their performance especially
http://blogs.msdn.com/youssefm/archive/2009/07/10/comparing-the-performance-of-net-serializers.aspx
There’s also a really good discussion here on Connect regarding the two serializers (XS and DCS) and a useful point that XS is still the way forward for WSDL/XSD First development as the DCS is only intended to support a simplified programming model and thus doesn’t support various xml constructs.
http://connect.microsoft.com/wcf/feedback/ViewFeedback.aspx?FeedbackID=451277
Hope this helps,
Cheers,
Benjy