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.
Related
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 developed a C# class library which contains numerous projects. I am using this as a common library across multiple different projects.
A number of different developers have recently joined the team and not being familiar with the library they are not sure what is contained with it. I have it well commented with the help of ghostdoc.
Is it possible to auto generate documentation using any tool of the library? I would like to run a tool against it that would generate documentation for me that I could make the developers aware of to read. I presume such a tool would generate the documentation from the comments.
I recommend using Sandcasle Help File Builder to generate documentation from your source code. You will want to review XML Documentation Comments as the quality and robustness of your generated documentation is directly related to the richness of the XML comments you use.
SHFB can generate HTML and/or compiled help documentation.
If you're using Visual Studio go to the projects' properties, select Build, then uner Ouput tick the XML documentation file checkbox.
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
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 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:
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
Does anyone know if there is an XSD file somewhere that can be used to validate the XML documentation that gets generated when you compile a C# project with the /doc option?
I want to modify that file manually after it's been generated and I'm looking for an easy way to confirm that I haven't damaged the structure of the file.
Thanks.
I finally broke down and wrote one: XSD for Xml Comments for .NET Documentation
Stumbled across this old question today.. I didn't see this by looking at Microsoft's documentation, nor when looking at other projects that I thought might have an interest in developing such a schema; namely, the sources for the Sandcastle and (long-defunct) NDoc projects.
Short of stepping back to try to define a schema on your own, one thing I could suggest would be to use one of the many tools that will generate an XSD from XML. Microsoft includes XSD.EXE as part of Visual Studio and its SDKs.
You could write up dummy source that exercises each of the XML documentation comment tags, build the XML documentation file for it, then use XSD.EXE. to generate an XSD from that, and use it to validate the XML doc after your processing is done. But I think that could turn out to be less trivial than it sounds.
Also, XML documentation comments refer to types and code elements, and there are many things a schema won't catch; e.g., verifying that the name attribute of a <param> tag still refers to an actual parameter name in your C# source. The compiler verifies such elements at build time. But if you post-process the XML documentation, you would need a custom tool that had a reference to the original C# source or generated assemblies to re-verify such references.
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 6 years ago.
Improve this question
Where can I find a control for WinForms that will highlight source code pasted into it? I would like one that has syntax highlighting support for many different languages but if it only works with C# I would be fine with that also.
Scintilla.NET is probably what you're looking for
Just recently have found a nice control from codeproject Fast Colored TextBox for syntax highlighting.
The only issue with using Rich Text Box as highlighter is slow performance on coloring, in cases when the size of the document is big. For a medium size documents this issue can be fixed by delayed highlighting.
As Open Source alternatives, give a look to:
dotNetFireball
ICSharpCode.TextEditor from SharpDevelop
Add ICSharpCode.TextEditor assembly reference to a project, choose assembly and controls for Visual Studio Toolbox. After that, you can put control to the Form. Surprisingly, you will not see Property to choose syntax highlight schema. Instead of this, you have to use method SetHighlighting. String parameter sets highlighting schema from available schemas list. These schemas are embedded into the control.
How to use, change schemas and download sample, look following article
If you're willing to pay for a control, I highly recommend this one: QWhale Syntax Edit. It's got a ton of features, comes with source code, and supports a lot of languages. I use it myself for C#, VB.NET, SQL (MS & Oracle), and it's got everything that VS provides.
Not sure if there is any out of the box non-thirdparty solution to this.
But, have you looked at Actipro SyntaxEditor component. LinqPad, the ubercool linq tool uses it for syntax highlighting and intellisense.
Check out the AvalonEdit control. There is a good article on CodeProject explaining how to use it.
you can try this http://www.codeproject.com/KB/edit/SyntaxHighlighting.aspx