Me: I'm a relative new-comer to the .NET platform.
Problem
In Java, you can add package level documentation to your project by creating a package-info.java or package.html file and storing in the package folder. How do I add equivalent documentation to my project in C# using Visual Studio 2010?
Background
I like to write documentation describing my motivations in the package/folder level context of the source code projects that I am working on. I have become very accustomed to this workflow in a variety of languages (specifically Java) and I believe that it is a good way to document my project.
C# will automatically turn the XML-based tripple-slash comments into intellisense documentation.
///<summary>This method does something!</summary>
///<parameter name="p1">The first parameter</parameter>
///<return>true, if the method completed successfully</return>
public bool DoSomething(int p1){
return p1 > 0;
}
When you compile your project into a class library and reference it in another project, the above will automatically be turned into a useful tooltip. In addition, the C# compiler can optionally produce an XML file with all of these comments alongside your DLL. This XML file can be fed into Sandcastle (as mentioned previously) and added to a documentation project as MSDN-style API reference.
The Sandcastle tool has its own project and documentation structure, so you'll want to start up a side project if you're going to add anything more than the XML-generated Intellisense reference.
The focus is a bit different in .NET, it has very good support for generating IntelliSense info. Documentation at your finger tips. I'm sure you're familiar with it when you used VS for a while, look up "xml documentation".
Off-line docs used to be covered by NDoc but the guy that supported it quit his project. The Sandcastle project took up the slack. Seems to be a bit laggy too these days btw.
Related
I use a production library (namely itextsharp) in my project, this library doesn't ship with intellisense documentation.
I'd like to build (partial) documentation project.
Is this possible without access to the source code?
I think that intellisense data for external libraries are defined in a xml file which should ship alongside the said library. It should also have the same named but an xml extension instead of dll.
There are a bunch of xml tags that Intellisense will expect which are documented on msdn. Also some open source libraries come with such documentation, like Unity for instance, which will give you a "working" example of such a xml file. You can find an example here on github
Using Visual Studio 2013 and .NET I've created set of widgets which I want to use in external projects. Each class and method is well documented with the XML-style comments. For example:
///<summary>...</summary>
When I use already commented code within the same solution, the appearing prompt suggesting how to finish the line contains my remarks. Nevertheless, when I tried to generate a DLL file with the code and use it in the external project the comments were not available anymore. How can I document code to make these hints visible in other projects using the compiled DLL?
If you want to use Code Documentation when referencing dll you have to generate XML documentation. XML documentation has to be in same folder that .dll is in.
When I create C# project in Visual Studio 2010, file Microsoft.CSharp.targets is included.
Is any documentation available for it?
Which targets in it, which properties are used?
It is especially useful when editing build script manually without VS.
The file with targets could be investigated manually (what I do from time to time).
But in such case it is not clear what is a matter of changes, what is by specification and what is no.
Everytime I need something about Microsoft.CSharp.targets I found it in different places.
I have not found "one place" with all described.
Does complete reference available?
Thanks.
No specific documentation I know of, it is an implementation detail for C# projects. You can find plenty of documentation about MSBuild in the MSDN library, the Microsoft.CSharp.targets file just contains targets that are specific to building a C# project.
The most important targets it implements are Build, Clean and Rebuild. They directly correspond to the commands you find in the VS build menu. The .csproj file merely sets properties that affect the outcome of the general targets. All of this is readily available on your machine, you can look at .targets files with an editor. There's just a whole lot of it and it is isn't exactly that easy to read, the concept of XML as a programming language is a bit, well, flawed. No debugger either.
I think I have a big problem.
I have a two projects solution.
First one is UI project.
Second one in an Algorithms Service.
I need to generate (or overwrite) a class (fileUI.cs) in UI part just before compiling it.
The main idea is that when you edit a class in de Services part (fileSA.cs) and you build the solution just a moment before the class in the UI part (fileUI.cs) is updated with Services part class information (fileSA.cs), and then, compiled.
I think its similar what VS does with the .designer.cs of every form(user control...)
I dont know if its possible...
Thanks a lot
You need T4 Template Here
Code Generation and T4 Text Templates
Visual Studio has a mechanism called single-file generators / custom tools that targets exactly this use case: generating a file (fileUI.cs in your case) when another file has changed (fileSA.cs).
Refer to the MSDN article Implementing Single-File Generators to learn how such a custom file generator is written.
P.S.: While this would be the appropriate mechanism, I don't think that it will work across the project boundary.
You can add a custom msbuild target in your project (right click on project -> edit project file). See msdn for more info about msbuild targets. You can run custom tasks as part of this target. A way to generate code is using T4 templates. More info here on running t4 templates as part of the build process. Oleg Sych has a lot of detailed explanations on T4 and is kind of the authority on the matter, so his site is a good read to start.
Here are the steps I take to create a package shipped to the end users:
Use visual studio 2005 Build the project (which is library DLL written in C#), both in debug and release mode.
I run doxygen and create documentation
I create a folder structure where I put my dll documentation and some release notes
zip it
ship it
the directory tree structure looks like this:
--NetApi:
--Api
--vs2005
--relesae
--dll
--debug
--dll
--documentation
--htmls files generated by doxygen
--ReleaseNotes.html
--Examples
I am thinking of rolling out a script to automate that. But before I do that, I would like to find out the common practices of packaging library api type of project, particularly structure, and tools used. References and examples are highly appreciated
Thanks
I am a big believer in continuous-integration and automated builds.
We have a rule in our shop that we never, ever, ever provide deliverables to a customer that were not produced by a fully automated, zero or one step build (that means that it took no more than 1 mouse click by a human to baseline, build, package, and release the thing.) These fully automated, one-step builds work by recognizing when a change is made to your source code control system, and automatically triggering the "build script."
For C#, I can recommend both CruiseControl.NET and Hudson.
I can also recommend the Pragmatic Project Automation series of books. Variants of this title should be available for both Java and .NET.
There are lots of prewritten build servers out there that can help you automate this.
For deployment I really like Inno Setup.
It is free, flexible, and can be easily customized to your tastes.