Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
How can create a documentation from all classes, methods and attributes comments in Visual Studio 2010 for the C# language?
Try Sandcastle and the Sandcastle Helpfile Builder. It creates CHMs and MSHelpfiles or HTML Pages in MSDN Style. Its simple to use and it can load Soultion Files.
Helpfile Builder with Sandcaste: http://shfb.codeplex.com/
Sandcastle only: http://sandcastle.codeplex.com/
You can create MSDN like documentation with
Sandcastle
Doxygen will generate nice HTML documentation from the comments in your code, provided that you follow a few simple formatting rules.
First it is worth saying that it is commendable that you want to document the API of your libraries so that others (or even you at a future date:-) will be able to use your code without having to read your code. That is a great step in itself!
There are a variety of tools that help automate this task, notably Doxygen and Sandcastle, as others have previously mentioned. I have not used Doxygen so I will restrict my comments to Sandcastle. Sandcastle, provided by Microsoft, is a great starting point but apparently is quite difficult to use, hence a number of motivated independent developers built more usable interfaces on top of Sandcastle. The premier one of these is Sandcastle Help File Builder (SHFB). With the GUI of SHFB you "simply" create a Sandcastle project, set the project properties to your liking, then build your documentation set as a web site or a CHM file or a couple other formats.
I wrote simply in quotes above because working in SHFB is the smallest part of the task in front of you--the much more vast task is decorating your code with appropriate and correct documentation comments (doc-comments) that serve as the "source code" for Sandcastle or other documentation engine. It takes a substantial investment of your time and energy to document all your code but I believe, as you may have inferred, that it is definitely worth it. Besides the aforementioned reason that others will be able to use your code much more easily, I find that documenting my code has one other important benefit--it helps me write better code. As I start documenting a new method or class I often remark to myself "Oh, this parameter would be more clear if it was called Y rather than X." or "Oops--this method is not generic enough for others; I need to add a Z parameter." or "Hah! This class does not handle these corner cases quite right." In other words, the act of describing your class or method or parameter makes you think carefully about it and thus writing doc-comments leads to better code.
So much for theory; for some practical advice and guideline for Sandcastle and SHFB, take a look at my article on Simple-Talk.com entitled Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code. This article thoroughly documents all the things I found through research and experimentation with SHFB. Accompanying the article is a handy wallchart that brings together all the documented and the undocumented elements and attributes that you may use in doc-comments. Here's a fragment of the wallchart to whet your appetite:
Related
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
I am going to admit that I am battling with changing face of C# and unlearning what I learnt since starting out with C#1.
I started years ago writing greenfield C# 1.1 code and also currently work a lot with maintenance work on code that is written with previous versions of C#.
Being exposed to the old ways of doing things is hard as I am battling to unlearn from code what I have written in the past and that I have to look at daily that was written in previous versions of C#. Having to maintain Java projects also doesn't help as it is similar to C#1. With time I could probably unlearn my bad practices but with project deadlines it is hard to do.
My lazy mind also is against me as its logic says if I use OO and DRY principles and the code compiles my boss is happy and thinks all is good when I am just not simplifying my code with new ways of doing things.
I have started reading Jon Skeet's C# in depth 2ed as what it does it gives the code solutions to do a specific tasks for each of C#1,C#2,C#3,C#4 each time showing the code examples how it simplifies code but I am finding it hard to remember and put into practice these new methods due to having to still deal with all this legacy code daily and still having to balance my jack of all trades dev jobs.
Is there an easy way to refactor between coding practices from C#1,C#2,C#3 to C#4 either on the fly or at compile time and give suggests either in English language or refactor the code for me.
Is there anywhere like a tool or a site I can see the changes for the same code between the C# versions excluding Jon Skeet's C# in depth book?
The latest version of ReSharper would be a helpful tool to move your C# forward in many respects quickly. It will point you to newer practices and make it quicker & less painful to employ them across existing code.
A couple forward-looking ReSharper refactorings that come to mind are:
Static to Extension Method...
Property to Auto Property...
Also, ReSharper will, for example, encourage you to use var for implicit declarations where possible.
CodeRush can do much the same, but I have not used it as recently.
To see the difference between where such tools' refactorings put you and where you started, diffing against prior revisions of your files in source control comes to mind.
For changes to the .NET BCL alongside C# as #stakx points out, consider digging into build warnings regarding deprecated code built against newer versions of .NET. Once you learn (as just one example) to replace uses of System.Xml.XmlValidatingReader with System.Xml.XmlReader, making the change in other places flagged for the former deprecated type will become quick.
What's Obsolete in the .NET Framework on MSDN characterizes the most recent BCL deprecations since .NET 1.1 and how to update affected code.
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'm trying to figure out how to automatically generate documentation for a single c# file in an ASP.NET project. I'm using VS 2010, and I have SandCastle, but I'm starting to get the impression it can only be used for a full project. The problem is that our entire project is huge and nothing but that one file needs documentation (it's the only one with functionality our clients use - everything else is internal)
I could do a batch script, but I'd rather not if there's a better way of going about this!
Does anybody have any ideas? Thanks very much in advance!
(as a side note, I saw this already and it did not help: Generating XML Documentation for single VB Class in WebSite Project )
I recommend using Sandcastle.
http://shfb.codeplex.com/
One thing you could do is have a post build task that pulls that portion of XML from the documentation file and then run Sandcastle or doxygen against your new XML file.
Have you tried StyleCop? It's aimed more at ensuring consistent coding practices, but does provide a little handy tool that allows you to quickly "Document this" on a constructor, method or property, etc. Might be worth a look to see if it's what you're after.
StyleCop
You can try https://www.docify.net/. Their whole thing is exactly this.
I've recently made a simple to use library that generates markdown documentation from C# code. All it takes is a class library dll file.
If you want to give it a try, here's a link on how to start using it with examples of generated documentation.
More informations : https://www.nuget.org/packages/BetaSoftware.AutoDocumentation
Doxygen might help. http://www.doxygen.nl/
At very least you can generate a word or pdf doc and then make a sub set of only the pages you need to provide.
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 6 years ago.
Improve this question
I'm beginner programmer in the amazing world named ".Net".
I've a lot of questions
well, what I should learn C# or Vb.net
What's the best blogs which talk about .Net technology and Open source projects
Where can I find good tutorials, free books and ideas of projects
how can I progress in ".Net"
please, share your knowledge , your OPML of your favorite blogs or web sites about ".Net "
I'm waiting your advices, opinions, etc.
As far as which language you should learn, well what are your experiences thus far? I prefer C# over VB.NET. Though, eventually, you should be able to program in VB.NET even if you say with C# as your primary language (the same is true vice versa for VB.NET). You might want to check the syntax of each language and see which you prefer just by first glance. You will probably find that whenever code examples are provided for .NET and both languages aren't present, typically the examples are in C#. This is not a big deal though. I find C# (and similar languages) to be less verbose but that is a preference. Here are some good resources. I highly recommend the LearnVisualStudio.NET videos; start with the beginner tutorials and advance to more advanced topics.
Some great resources include:
http://www.dotnetrocks.com (podcast)
http://www.se-radio.net (general software engineering podcast)
http://www.haacked.com (Phil Haack's blog)
http://weblogs.asp.net/scottgu/ (Scott Guthrie's blog)
https://stackoverflow.com/questions/551315/which-c-net-blogs-do-you-read (previous question with a good list of blogs)
http://www.learnvisualstudio.net (good place to find video courses, cheap)
https://stackoverflow.com/questions/54423/best-net-podcasts (previous question)
What good technology podcasts are out there? (more podcasts)
Open Source projects:
http://www.codeplex.com is great for Open Source .NET projects.
Also:
http://csharp-source.net/ (not bad, some projects are old and not maintained)
http://sourceforge.net/softwaremap/trove_list.php?form_cat=271 C# as SourceForge
Open Source C# Opportunities (previous question with good infor)
Also check http://www.codeproject.com/
I'd start with Fabulous Adventures In Coding, which is a great blog by one of the people who actually work on C#. Then i'd also take a look at CodeProject and MSDN. Finally, you can't forget Joel Spolsky's web site!
For Regexes, look no further than here. Cosmos is a neat project though a little heavy for beginners, and DevExpress has the best VS addin this side of the earth! Personally, i don't like ReSharper but plenty of other people do.
(marking it CW so anyone can contribute)
Excellent suggestions so far. Another site to always keep in mind for open source code is Google Code. Plus Google has excellent search features for finding just about anything in their code base.
Things i am following
https://stackoverflow.com/
http://www.codeplex.com/
http://msdn.microsoft.com/hi-in/default.aspx
If you are interested in web development, check http://www.asp.net.
Also, checkout MSDN Magazine, 4 Guys From Rolla, and the Linq Project.
You can find a Comparison of C# vs VB.NET here
Also this Article in CodeProject describes the complete differences between C# and VB.NET. You will get large number of opensource projects from CodeProject
You can find an exiting project TextPad, which will help you to learn more in C#
I also had these question in my mind when I started learning .NET. I prefer C# over VB. But then its purely a personal choice. In my view start with a nice book like Beginning Microsoft Visual C# 2008 or Head First C#. And the online source which I find very useful MSDN.
As to your question whether to learn VB.NET or C#... Well, there are personal preferences and there are realities.
If you want to make a living out of this, keep in mind that relatively and generally speaking c# will make you more employable.
Example. As of right now, Dice lists 4421 matches for c# versus 1131 for vb.net.
I can recommend "Beginning ASP.NET 3.5 in C# 2008: From Novice to Professional" from Mathew MacDonald. It does not rely on deep C# knowledge and even for someone who knows C# it's interesting to read. I'm almost half through, and it is really nice to read.
Don't be shocked by the almost 1000 pages - lots of code listings and pictures are inside.
I think there is even a VB.NET edition, but I prefer C# - and I still think that this is the language Microsoft puts more focus on.
For GDI (graphics) programming in C# / VB.Net, look at the "Beginners guide to GDI+" section at bobpowell.net.
I have worked through many of the advanced topics, and they're very well written and give great examples.
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
I am building the documentation for our C# API containing:
A general overview and description of the current state as a doc/pdf file.
A class library API in a .chm file using Sandcastle.
Questions:
Should I merge these two into the same .chm file? What is a good way to merge them?
I need to exclude certain classes/packages. How can I specify that in SandCastle?
It generates documentation for the VB code and the Visual C++ code. How can I change this? Or should I leave it, knowing that I am only using safe code?
Where can I find HTML Help 2.x Viewer Path on my system?
Edit:
The comments I make above methods, fields and classes are not generated in the documentation.
What should I do?
I recommend that you use Sandcastle Help File Builder from Codeplex. You can easily include and exclude namespaces, but I am unsure how to go about excluding a single class. You can set the option to only generate documentation for public/protected classes, but I do not know if that will fit your scenario.
You can also target a specific language in SHFB, as to your second question.
Additionally, you can use MAML within SHFB for conceptual documentation, such as you mention as being in the doc/pdf file. You should be able to use Doc2Maml for to migrate your existing documentation. Doc2Maml is a part of DocProject, but it appears that you might be able to run it standalone.
Edit in response to comment:
Directions are for SHFB 1.8.0.1. I do not remember the exact way to do it in 1.7, but I believe it is similar:
Under "Comments" group in the Project Properties tab, click the ellipsis to the right of "NamespaceSummaries".
In the checkbox list in the top left, uncheck any namespace you want to exclude.
This is also the screen where you put namespace summaries in.
In addition to Sand Castle as mentioned above, I would also recommend looking at FxCop and StyleCop to help make sure your code and documentation is up to CLS Compliance standards.
Sandcastle Help File Builder (SHFB) itself has a .chm file where you can find the answers to questions like "how can I exclude certain namespaces or classes from the generated doc?"
You may think I know the answer and I am being snarky by not telling you. Not true. But I was skimming the doc last night and saw an entry on this very topic.
I don't know why you wouldn't just leave in the VB and C++ stuff; there may in the future be someone who uses a language that is (shockingly) not C# with your library. The language is normally settable by the help viewer, so C# devs can ignore the VB syntax.
As for merging, SHFB has a mechanism to add in arbitrary HTML in an arbitrary hierarchy. In the GUI it is here:
http://www.freeimagehosting.net/uploads/7de19ea568.jpg
Using this, you could convert the PDF/DOC to HTML and then just embed it in the .chm.
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 9 years ago.
Improve this question
Can anyone recommend a good application that could be used to convert VB.NET projects to C#, without having to do too much manual work?
We've used Reflector to do small libraries manually, but some of the larger projects will be too slow and complex to do this manually.
You can use Lutz Roeders Reflector (http://www.red-gate.com/products/reflector) which can decompile whole Assemblies into Visual Studio projects. This way you can convert from ANY .NET Langauge into one of the supported languages of this program (C#.VB.NET,MC++,Delphi,Chrome)
Tangible Software do various converters, including VB to C#.
I've played with it a little bit as they're kind enough to give me a copy for free, but I can't say I've stress-tested it. When I've used it it's been fine though - certainly worth a try.
A few things to keep in mind...
1) Depending on how the VB.Net code was written, automatic conversion may or may not be 100% possible. VB.Net allows a "looser" coding style that would be ambiguous to C#. So, some manual intervention may be needed.
2) If the VB.Net code functions correctly, you may want to just leave it as VB.Net. Both VB.Net and C# projects can co-exist within the same solution.
The far best tool for this is Econ Netvert which can be found on CodePlex
http://www.codeplex.com/econnetvert
SharpDevelop has this feature, but I haven't used it enough to know if works reliably. It seems to be a pretty good otherwise, so it's worth a try though.
The best and fast converter I have seen so far is http://converter.telerik.com/
Nicely presented using RAD AJAX Controls.
Note: It converts only code snippets and not projects as a whole.
There's also the free online converters up at developerfusion :)
SharpDevelop is quite good, but at my company we've found VBConversions to provide a much more complete conversion. It's a commerical app though, but for the time saved over SharpDevelop it was a no-brainer for us.
As a specific example, one thing we found that SharpDevelop didn't convert correctly was VB indexes, which use curvy brackets. It seemed unable to distinguish between indexes and method calls so didn't convert the indexes to square brackets. VBConversions converted them fine. This one thing made it worth its purchase for us.
It looks like the Tangible Software product works very similarly to VBConversions.