I need to make summary for two different languages, i know how i can do it for one language
/// <summary>
/// Constructor
/// </summary>
/// <param name="FilePath">Full path to file</param>
How could i add German variant?
Is, it possible? If yes, show me some example please.
Unfortunately the XML documentation "system" is not that flexible.
I don't have a good solution for you, but you can look at using some XML editors to take the original XML produced by Visual Studio and translate it to German - if the XML structure remains the same, you can use the normal tooling (SandCastle or whatever) to produce the German documentation.
Update:
The approach that #ta.speot.is linked to in his comment is interesting and can be made to work.
In general, you have a complete copy of the documentation comments in a different language, only using an xml:lang attribute on the <summary> element - the produced document will contain all the XML elements and you can use XSLT to transform and select the language.
No, that's not possible, afaik. VS XML documentation mechanism currently supports only one comments block per class member.
Related
What is the use of XML comments in C# than signal line and multiple line comments.
i.Single line
Eg:
//This is a Single line comment
ii. Multiple line (/* */)
Eg:
/*This is a multiple line comment
We are in line 2
Last line of comment*/
iii. XML Comments (///).
Eg:
/// summary;
/// Set error message for multilingual language.
/// summary
From XML Documentation Comments (C# Programming Guide):
When you compile with the /doc option, the compiler will search for
all XML tags in the source code and create an XML documentation file.
Also XML comments used by Visual Studio for IntelliSense:
/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass{}
Will give you nice hints when you are typing code or hovering cursor over member which has xml comments:
NOTE: Usually you should add xml comments only to publicly visible types or members. If member is internal or private, then it's good, but not necessary. There is nice tool GhostDoc (available as extension to Visual Studio) which can generate XML comments from type or member name. It's nice to check if you have good naming - if generated comment is not clear, then you should improve name of member.
I also suggest use simple (non-xml) comments as little, as possible. Because comment is a form of code duplication - it duplicates information which you already have in your code. And here is two problems:
Your code is not clear enough and you should improve it (renaming, extracting classes or members) instead of adding comments
When code changes, comments often stay unchanged (programmers are lazy). So when time passes comments become obsolete and confusing.
Good comments should describe why you writing code instead of duplicating what code is doing.
XML comments, starting with ///, will get picked up by IntelliSense and it will get shown in a pop-up when looking at it from elsewhere. There is a MSDN page explaining how it works.
They will also be picked up by numerous tools that build documentation files, etc.
From MSDN:
When you compile with the /doc option, the compiler will search for
all XML tags in the source code and create an XML documentation file.
To create the final documentation based on the compiler-generated
file, you can create a custom tool or use a tool such as Sandcastle.
http://msdn.microsoft.com/en-us/library/b2s063f7.aspx
The XML comments are used to build API documentation which is readable by external tools. IntelliSense also reads these, and uses the contents to show the docs for your code in the assistance tooltips as you type (and in the Documentation window).
The compiler (optionally) extracts all those comments and puts them in a single standalone XML file next to your assembly; this can be parsed.
The idea was to have something like JavaDoc. Unfortunately Microsoft has failed to provide a mainstream mature tool to do so.
When you create a Dll assambly Xml comments provides the dll's user some information about function or something
Code in all languages usually allows for special comments. These comments can then be parsed by a process which creates automatic documentation of the code. Many libraries are documented this way.
In C# these tools are provided by Microsoft and you use the XML comments to declare that the comment should be picked up by the documentation process - if you have one set up. The comments are also picked up by auto complete.
See also doxygen, JavaDoc for implementations for other languages. See related question Good alternatives to Sandcastle to generate MSDN-style documentation
I am looking for an alternative to C#'s XML source code documentation which introduced by the very nature of XML a lot of noise that is heavy on the eye and more work to write:
/// <summary>
/// This is text of importance. Linking to
/// <see cref="AnotherClass>is somewhat verbose.</see>
/// </summary>
/// <param name="andSo">is parameter documentation</param>
Instead I would like to use Markdown for the documentation:
/// This is text of importance. Linking to [an](OtherClass) is less verbose.
///
/// Empty lines would make a new paragraph
///
/// aParameter
/// : could possibly be documented in definition-list manner
/// as in http://bit.ly/1l9ik26
I could bet I found a question and answer for exactly this on Stackoverflow before. Unfortunately I don't manage to find it anymore. I tried all variations of search keywords I could imagine without luck. So I hope that any of you will find the duplicate. At least my question will add some value to SO by providing a "proxy" to the existing Q&A with different wording, thus improving the odds for future visitors to find their information.
Update:
I guess I finally found the other question by using a different search engine: Markdown for automatic doc generation?. It seems that Doxygen supports Markdown. Doxygen supports C#, too. But this probably doesn't go a long way as for the requirements that #Sam Harwell mentioned.
This gist does the job pretty well: https://gist.github.com/formix/515d3d11ee7c1c252f92
The resulting doc looks like that: https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md
Theoretically, your example could be used to provide proper documentation files for C# projects. However, I recommend you avoid this approach for the following reasons.
Visual Studio will not be able to consume the comments directly. They will need to be run through a Markdown processor to produce properly-formatted XML documentation files prior to working. This means you'll only ever be able to get proper documentation for referenced projects, and not for the current project. Also, if you aren't generating XML output, then you aren't producing any output other developers are able to use when they reference your library.
Both Roslyn and the SHFB project are working to improve IntelliSense support for XML documentation comments. At this time, SHFB focuses on showing its custom documentation tags (e.g. <preliminary/> and <see langword="null"/>), and Roslyn focuses on IntelliSense support for the cref attribute value of see and seealso tags. To my knowledge, there is no push for supporting an alternative method of documenting C# code.
Docfx
https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
DocFX is an API documentation generator for .NET, which currently supports C# and VB. It generates API reference documentation from triple-slash comments in your source code. It also allows you to use Markdown files to create additional topics such as tutorials and how-tos, and to customize the generated reference documentation
You can use Vsxmd (https://www.nuget.org/packages/vsxmd). More details on how to use you can find on github page of the package (https://github.com/lijunle/Vsxmd)
What is the use of XML comments in C# than signal line and multiple line comments.
i.Single line
Eg:
//This is a Single line comment
ii. Multiple line (/* */)
Eg:
/*This is a multiple line comment
We are in line 2
Last line of comment*/
iii. XML Comments (///).
Eg:
/// summary;
/// Set error message for multilingual language.
/// summary
From XML Documentation Comments (C# Programming Guide):
When you compile with the /doc option, the compiler will search for
all XML tags in the source code and create an XML documentation file.
Also XML comments used by Visual Studio for IntelliSense:
/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass{}
Will give you nice hints when you are typing code or hovering cursor over member which has xml comments:
NOTE: Usually you should add xml comments only to publicly visible types or members. If member is internal or private, then it's good, but not necessary. There is nice tool GhostDoc (available as extension to Visual Studio) which can generate XML comments from type or member name. It's nice to check if you have good naming - if generated comment is not clear, then you should improve name of member.
I also suggest use simple (non-xml) comments as little, as possible. Because comment is a form of code duplication - it duplicates information which you already have in your code. And here is two problems:
Your code is not clear enough and you should improve it (renaming, extracting classes or members) instead of adding comments
When code changes, comments often stay unchanged (programmers are lazy). So when time passes comments become obsolete and confusing.
Good comments should describe why you writing code instead of duplicating what code is doing.
XML comments, starting with ///, will get picked up by IntelliSense and it will get shown in a pop-up when looking at it from elsewhere. There is a MSDN page explaining how it works.
They will also be picked up by numerous tools that build documentation files, etc.
From MSDN:
When you compile with the /doc option, the compiler will search for
all XML tags in the source code and create an XML documentation file.
To create the final documentation based on the compiler-generated
file, you can create a custom tool or use a tool such as Sandcastle.
http://msdn.microsoft.com/en-us/library/b2s063f7.aspx
The XML comments are used to build API documentation which is readable by external tools. IntelliSense also reads these, and uses the contents to show the docs for your code in the assistance tooltips as you type (and in the Documentation window).
The compiler (optionally) extracts all those comments and puts them in a single standalone XML file next to your assembly; this can be parsed.
The idea was to have something like JavaDoc. Unfortunately Microsoft has failed to provide a mainstream mature tool to do so.
When you create a Dll assambly Xml comments provides the dll's user some information about function or something
Code in all languages usually allows for special comments. These comments can then be parsed by a process which creates automatic documentation of the code. Many libraries are documented this way.
In C# these tools are provided by Microsoft and you use the XML comments to declare that the comment should be picked up by the documentation process - if you have one set up. The comments are also picked up by auto complete.
See also doxygen, JavaDoc for implementations for other languages. See related question Good alternatives to Sandcastle to generate MSDN-style documentation
I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference.
In general, what are some good guidelines when writing comments for a class and for a method? What should the NDoc comments say? What should they not say?
I find myself looking at what the .NET framework comments say, but that gets old fast; if I could have some good rules to guide myself, I could finish my docs a lot faster.
In comments used to build API documentation, you should:
Explain what the method or property does, why it exists at all, and explain any domain concepts that are not self-evident to the average consumer of your code.
List all preconditions for your parameters (cannot be null, must be within a certain range, etc.)
List any postconditions that could influence how callers deal with return values.
List any exceptions the method may throw (and under what circumstances).
If similar methods exist, explain the differences between them.
Call attention to anything unexpected (such as modifying global state).
Enumerate any side-effects, if there are any.
If you end up with comments that don't add any value, they're just wasteful.
For example
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
...you added absolutely no value and just added more code to maintain.
Too often code is littered with these superfluous comments.
StyleCop provides hints for code and commenting style. The suggestions it gives are in line with the MSDN documentation style.
As for the contents of the comment, it should give the user of your code enough information on what kind of behavior to expect. It should also answer potential questions the user might have. So try to use your code as someone who doesn't know anything about the code, or even better, ask someone else to do so.
For properties, your comment should indicate whether the property is read only, write only or read write. If you look at all official MS documentation, property doc comments always start with "Gets ...", "Gets or sets..." and (very rarely, avoid write only properties usually) "Sets ..."
Don't forget what's a valid XML is. For example:
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(Error: invalid XML).
I write the <summary> comment to include the information I would want to know if I was the one calling that function (or instantiating that class).
I write the <remarks> comment to include information I would want to know if I was tasked with debugging or enhancing that function or class. Note: this doesn't replace the need for good inline comments. But sometimes a general overview of the inner workings of the function/class are very helpful.
As stated on the MSDN page, you use XML documentation comments to generate documentation automatically, so it makers sense if you're writing an API and don't want to work twice at both code and documentation, with the added benefit of keeping them in sync - every time you change the code, you modify the appropriate comments and regenerate the docs.
Compile with /doc and the compiler will search for all XML tags in the source code and create an XML documentation file, then use a tool such as Sandcastle to generate the full docs.
One thing about comments is UPDATING them. Too many people alter a function then don't change the comment to reflect the change.
In our company we write excessive Xml comments. A typical method is has to be documented like this:
/// <summary>
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param>
/// <returns>
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>.
/// </returns>
bool Contains(ISchedule schedule);
/// <summary>
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/>
/// from this <see cref="IScheduler"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param>
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception>
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception>
void Remove(ISchedule schedule);
As you can see nearly every noun which can be referenced using a <see cref> tag.
I find this too much. Most of our code files are so blown up with such comments. Makes the comments section nearly unreadable.
What do you think? Do you like this kind of documentation in the code or not?
As usual I think there is no black / white answer to such a kind of question, that's why I made it wiki.
EDIT:
My question was not if the see-ref-tags itself are useful per default. It is clear that the generated links in the .chm file (or any other kind of generated docu) are very useful. My question was if it's is really useful to tag every occurrence of every "linkable" noun in the comments.
We use Sandcastle to generate the docu every night. Unfortunately it is very rarly used by other developers, but that's another issue.
Personally, I think what you have is a bit overboard.
The purpose of the "see" references is to provide good linking between topics in the generated help documentation after parsing.
In your case, your business-specific libraries are referencing language items, ie:
<see langword="true"/>
I personally feel that hyperlinks to other related objects in your library is a very useful feature. It makes reading the help much more usable for your users.
Hyperlinks to language elements is something that I feel should only exist inside the language help itself. In the case of a third party library, this just "muddles" up the message by putting links everywhere. This makes the good links less effective, since they get hidden in the mess.
I would suggest liberal use of linking to related classes in your library. I would avoid adding hyperlinks to base library classes, except in specific instances where it is particularly useful for some reason (rare). Linking to "true" and "IDisposable.Dispose", etc, doesn't really add a lot of value.
Trust your user to understand the base framework, but teach them about your library.
The point of all of those is that when something like Sandcastle is used to generate HTML or CHM docs for the library, that those docs get hyperlinked navigation between objects. So the question then is, when you use MSDN do you find it useful to be able to click on a class name a have it navigate to the help for that class, or are you ok with copying it and pasting it into the search field?
Yes, it bloats the code (though comments can be collapsed), but if you actually ship documentation to others, it's pretty darned helpful.
When you're working with Visual Studio, then you can use the CR_Documentor plugin (it's free, you can get it here) for WYSiWYG-reading/writing your comments. It looks like generated help form Sandcastle or NDoc, but is rendered on the fly.
It's really useful, and you don't have to care about the raw xml comments at all.
As ctacke said, it's very useful for hyperlinking. However, if you're not actually shipping documentation, all that tagging makes the documentation virtually impossible to read. In that case, the documentation is for the (edit: INTERNAL) developer, and if he or she can't read it, you're wasting your time.
As a rule, I tend to the first reference to a type or member, and leave the rest unlinked. It leaves the comments pretty clean, and still provides meaningful linking.
There is a particular reason for these sorts of comments: they can be used to generate documentation or to add extra information to autocomplete. I agree that they are overly verbose and difficult to read for most situations, but they are good to add to an interface which you are going to expose externally.
I would recommend using an editor which allows you to turn comments on and off.
Some languages allow you to store comments as metadata on variables and functions, which is a nice alternative.