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.
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 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 7 years ago.
Improve this question
Is there any way to represent class's source code as objects? I'd like to navigate through methods, theirs body etc. How tools like stylecop, ReSharper do it in Visual Studio 2010? Are there any external libraries which take as input source code file and produce representation of objects? Which i could read, modify or analyze?
As for already compiled assembly. Reflection can give you most info about object structure. But to get real code, you need to get down to IL.
As for code, that is open in Visual Studio, then VS exposes COM interface, that many of those plugins use. EnvDTE is managed wrapper around this interface. But documentation is scarce.
NRefactory will do this for you:
http://wiki.sharpdevelop.net/NRefactory.ashx
Edit: This is a "parser" which is what you want. It converts C# code into an abstract syntax tree which can then be modified with code and translated back to C#.
If you'd like just to list method, class, property names, then Reflection is a good simple solution - e.g. see simple tutorial like http://www.java2s.com/Tutorial/CSharp/0400__Reflection/ListMethods.htm
If you want more detailed analysis, including method bodies, then it might be a good idea to start from the source code from one or more of the Reflector replacements - e.g.
ILSpy - http://wiki.sharpdevelop.net/ILSpy.ashx
smooth reflector http://blog.smoothfriction.nl/archive/2011/02/07/building-your-own-reflector-with-mono-cecil-and-the-codedom.aspx
list here - Open Source Alternatives to Reflector?
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 a PDF with some meta data in XMP XML format attached to the end. What is the correct way of parsing and using this meta data?
At the minute i have a working solution using C99, parsing each character in the file, starting at the beginning and using loops until i reach a tag im after and then recording the contents until i reach the closing tag. I can't see this as the best way of doing things.
I'm now rewriting this program using C# + Mono (not .NET) and i wonder if there is a magic framework class for this task instead of just imitating the C99 version? (Also, i can only rely on third party libraries if they don't contain any p/invoke stuff, etc.)
I'm using Mono because i need this app to be cross-platform.
Adobe has published the XMP specification. Give it a try. You need to find out what XMP schema the XML uses and parse it accordingly.
If you can get the complete XML as a string, you can use XmlDocument.Load to get the complete XML in memory for querying.
You can then use XPath with the XmlDocument.SelectNodes method in order to get to your data.
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.