Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
So I'm using WCF, and want to document my interface(s) and services to give to another company for an internal app. What's the best way to document those interfaces? I'd prefer having the documentation inline with the code, and then have something prettify to output HTML, but am not sure if there's a recommended way to do it.
We use WCFExtras (http://www.codeplex.com/WCFExtras) for that.
Among other features it allows live exporting of your code xml comments into the generated WSDL, for example check how these xml comments:
/// <summary>
/// Retrieve the tickets information for the specified order
/// </summary>
/// <param name="orderId">Order ID</param>
/// <returns>Tickets data</returns>
[OperationContract]
TicketsDto GetTickets(int orderId);
get reflected in the WSDL of that interface:
<wsdl:operation name="GetTickets">
<wsdl:documentation>
<summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns>
</wsdl:documentation>
<wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/>
<wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/>
</wsdl:operation>
An excerpt from their docs:
Adding WSDL Documentation from Source Code XML Comments
This extension allows you to add WSDL documentation (annotaiton) directly from XML comments in your source file. These comments will be published as part of the WSDL and are available for WSDL tools that know how to take advantage of them (e.g. Apache Axis wsdl2java and others). Release 2.0 also includes a client side WSDL importer that will turn those WSDL comments to XML comments in the generated proxy code.
Do use XML docs for that. There are a lot of smart meta-tags that will allow you to put code samples in them, references between operations, thrown exceptions etc.
Then you can use Sandcastle (+ some GUI you can find on Codeplex) to generate either chm, or html documentation.
I use two XSL files - one to document the WSDL for the operations, one to document the XSD for the data being passed around.
Unfortunately, so far, I haven't found a single cohesive solution, so I work with two XSLT files which transform the WSDL and the XSD respectively into HTML documentation.
WSDL Viewer does the job for the WSDL and produces a first HTML document, and xs3p does the same for the data contain in the XSD file.
Using the XML output from the compiler is nice...but it's been my experience that it's difficult to express the complete complexity of a service and it's expected invariants, dependencies, etc. in comments alone. You're better off maintaining a separate real document (Word, HTML, Wiki) to cover it all.
I will put my interface contract into a common dll and hand that out. It gives them both the xml comments on the contract without giving the details of the service as well as allowing them to implement the service in an offline mode for testing until they're ready to use it. On top of that, they can bypass the wsdl and use ChannelFactory to create a channel.
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
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I have an open-source project (here) whose documentation is currently in French. The documentation is generated from XML comments in code, using Sandcastle. Now I would like to translate the documentation to English and provide documentation in both languages, but I don't really know where to start...
Do I need to extract the XML comments from the code and put them in a separate file? If yes, are there any tools to automate the process?
I'm using Sandcastle Help File Builder to build the documentation; do I need to create a separate project to build the doc in English, or can it be done from the same project?
Are there any tools to help in the translation process? e.g. display the original and translated doc side by side?
I'm also interested in links on how to produce multilingual documentation, as I couldn't find anything useful on Google...
One strategy, which would require some coordination with the Sandcastle XSLT files, would be to use the xml:lang attribute on your XML documentation. Visual Studio 2010 allows multiple tags to remain (although you may get complaints about duplicate tags).
/// <summary>
/// Gets or sets the fill size of the load operation.
/// </summary>
/// <summary xml:lang="fr">
/// Obtient ou définit la taille de remplissage de l'opération de chargement.
/// </summary>
public int FillSize
{
get;
set;
}
Resulting output:
<member name="P:Namespace.MyAttribute.FillSize">
<summary>
Gets or sets the fill size of the load operation.
</summary>
<summary xml:lang="fr">
Obtient ou définit la taille de remplissage de l'opération de chargement.
</summary>
</member>
We did that like this :
We put a "<EN>" tag after all our documentation tag like this :
/// <summary>
/// Description du produit
/// <EN>Product's description</EN>
/// </summary>
Then in the sandcastle xslt file (Development/presentaton/vs2005/transforms/main_sandcastle.xsl) we went to the template matching "param" (line 95 for us) and we added
<span class="trad">
<xsl:value-of select="msxsl:node-set(.)/EN"/>
</span>
And then you can change the css to display the translation in your favorite color.
One possible strategy would be having a default language in code, and supply translations separately.
No matter which localized languages i would have finally, i'd prefer to choose English as the default/fallback language of the documentation.
Code structure provides indexing for your translation database, for example:
Type, NameWithNamespace, OptionalParameterName
"member", "MyProject.Core.Loader.FillSize", ...
You could have a tool that would allow for translation in a UI for each namespace/member.
You can have a separate team of translators looking through the items that have no translation yet, and supply translations.
And you can start shiping a translated documentation as your ship a release as soon as you get the amount of translated items above a threshold.
A changed default translation would indicate that you need a new translation for all other languages too.
Of course, if you do a major namespace-only changes, you can remap the namespaces as an ad-hoc remapping operation in database.
If you run opensource project, it makes sence to use a collaborative online translation tool.
One example of such collaborative translation strategy implemented in production is
https://translations.atlassian.com/
Basically you could just step in and start contributing translations online.
It is set up to translate the products themselves, not the documentation, but the same practice apply.
Just in case anyone needs a solution there is nuget package called Surviveplus.XmlCommentLocalization. Stunning!
You have yourself a tricky one. There really isn't a "best practise" since most software is developed in English.
That being said, if you look at other multi lingual documentation, how do they handle this problem?
Take International Standards. Something like ISO 9001. You have the same document (ISO 9001:2008) available in English, French, Russian etc.
Or ISO 5247-2 has the one document in English+French+Russian.
How would you handle changes? Say I give you a patch, but my comments are only in English, what would your process be? What if you have patch A in English, patch B in Spanish and patch C in English + French?
Another option is to fork the project. Have the main branch be in French with the latest build, then bring the other languages up to date in their own time?
Separating the comments in your source code would get messy to maintain. You are then basically using a resource file in your build script.
Is this a solved problem already? If you think of any large, multi lingual, open source project, how do they handle it?
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
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 8 years ago.
Improve this question
I've been using the following home-grown configuration frameworks to manage configuration of my projects for a few years now:
The first one mimics Java's .properties files (a bunch of supergroup.subgroup.property=value lines with support for collections) and works fine for many situations (I find it's best for small applications). This one is good for very simple configuration
A second based on DataContractSerializer (and optionally XmlSerializer) which allows all of the functionality of the first one with all of the perks of XML and fewer plumbing to make it work. This one is good but impractical and cumbersome to manage without an explicit UI over the top of it to mitigate the headaches of teaching end users to modify XML.
Both of the existing frameworks marshal to and from POCOs without issue to allow access to configuration values through properties/fields (through manual/automatic serialization respectively), so they are very easy to work with as a developer.
Now that I am reviewing their ability to enable database and fluent configuration, I'm looking for an out-of-the-box (preferably open source) alternative. I have no problem with reworking all of my existing projects if I can reduce unnecessary code duplication and allow them access to DB and fluent configuration (in addition to their existing abilities).
Any suggestions or is it worth rolling my own to get the features I'm after?
In my research I found this potentially duplicate question which is answered by Nini but it hasn't been updated in almost 2 years and only supports the options I already have covered (based on its documentation anyway). Did I miss something in my research or is there a better alternative?
Update
The explicit features I'm after are:
XML files
INI/Java-like properties files
Database (at least MS SQL and SQLite, optionally MySQL and any others as you could imagine)
Fluent (code generation not required)
Some sort of extension API to allow me to add my own sources
It definitely needs to serialize to/from any of the data sources to be accessible through properties/fields.
Enumeration support
I'd be interested in extending an existing framework if it is open enough to do what I need to do, but otherwise it probably isn't a good fit.
UPDATE
The functionality from the existing System.Configuration namespace is great, and I'm familiar with how well it can work but in general it doesn't do what I am looking for. I've used it (even in advanced scenarios) but being that it only allows limited XML extensibility: it just isn't what I am after.
If I have to give on any of the predefined functionality, I'd say the fluent configuration is the least important (it'd be extremely difficult to provide a valuable interface for this generically anyway). I'll just bolt together something on top of whatever I find.
The mere fact that it has been over 24 hours (and > 125 views) and no one has been able to offer a reasonable alterative tells me it likely doesn't exist. I'll start on my own in hopes that someone can provide an interesting alternative.
Creating a general purpose configuration manager is very very demanding task. Over the years, I haven't seen any config framework emerging and I don't thing I will. Just have a look at the System.Configuration namespace and you can see how expensive It would be to try to match a similar set of features. Most of the time, configuration requirements are very project specific and there is no silver bullet.
My advice would be to stick to your own solution, as long as it is easily unit-testable and does the job.
Please check it out Cinchoo Configuration Framework, it offers most of the features you looking for.
Here is the simple way to define and use the configuration object using Cinchoo framework
namespace HelloWorld
{
#region NameSpaces
using System;
using Cinchoo.Core.Configuration;
#endregion NameSpaces
[ChoConfigurationSection("sample")]
public class SampleConfigSection : ChoConfigurableObject
{
[ChoPropertyInfo("name", DefaultValue="Mark")]
public string Name;
[ChoPropertyInfo("message", DefaultValue="Hello World!")]
public string Message;
}
static void Main(string[] args)
{
SampleConfigSection sampleConfigSection = new SampleConfigSection();
Console.WriteLine(sampleConfigSection.ToString());
}
}
Very first time, when you run the application, Cinchoo framework automatically generates the configuration section as below. Then onwards, you can control them either through configuration source or by code.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="sample" type="Cinchoo.Core.Configuration.ChoNameValueSectionHandler, Cinchoo.Core, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b7dacd80ff3e33de" />
</configSections>
<sample>
<add key="name" value="Mark" />
<add key="message" value="Hello World!" />
</sample>
</configuration>
The solution I have for you comes within the Spring Framework .NET, which among other greats features have the PropertyPlaceholderConfigurer class.
This class aims to externalize some of the properties you have in your xml config files. So, instead write down literal values (like connection strings, passwords, or any other parameters) you put placeholders, like ${sql.server}, ${sql.password} that will be automatically replaced by the external values.
Those external values can be in anywhere. In my company's case, since we have legacy system that uses the same values, we've put them in the windows registry (which I obviously not recommended for new projects).
But, be aware that this is not a standalone feature of Spring, it comes with Spring.Core, and you will have to use the spring configuration files and Dependency Injection features.
http://www.springframework.net/doc-latest/reference/html/objects.html#objects-factory-placeholderconfigurer