Is there an easy way to produce MSDN-style documentation from the Visual Studio XML output?
I'm not patient enough to set up a good xslt for it because I know I'm not the first person to cross this bridge.
Also, I tried setting up sandcastle recently, but it really made my eyes cross. Either I was missing something important in the process or it is just way too involved.
I know somebody out there has a really nice dead-simple solution.
I'm reiterating here because I think my formatting made that paragraph non-inviting to read:
I gave sandcastle a try but had a really hard time getting it set up.
What I really have in mind is something much simpler.
That is, unless I just don't understand the sandcastle process. It seemed like an awful lot of extra baggage to me just to produce something nice for the testers to work with.
You're looking for Sandcastle
Project Page: Sandcastle Releases
Blog: Sandcastle Blog
NDoc Code Documentation Generator for .NET used to be the tool of choice, but support has all but stopped.
Have a look at Sandcastle, which does exactly that. It's also one of the more simpler solutions out there, and it's more or less the tool of choice, so in the long run, maybe we could help you to set up Sandcastle if you specify what issues you encountered during setup?
You should also use the Sandcastle Help File Builder. It provides you with a ndoc like GUI for generating help files so you don't have to do anything from a command prompt.
Welcome to the Sandcastle Help File Builder Project
I've just set up Sandcastle again. Try installing it (the May 2008 release) and search for SandcastleGui.exe or something similar (it's in the examples folder or so).
Click Add Assembly and add your Assembly or Assemblies, add any .xml Documentation files (the ones generated by the compiler if you enabled that option) and then Build.
It will take some time, but the result will be worth the effort. It will actually look up stuff from MSDN, so your resulting documentation will also have the Class Inheritance all the way down to System.Object with links to MSDN and stuff.
Sandcastle seems a bit complicated at first, especially when you want to use it in an automated build, but I am absolutely sure it will be worth the effort.
Also have a look at Sandcastle Help File Builder, this is a somewhat more advanced GUI for it.
Follow this simple 5 step article and you are pretty much done. As a bonus you can use H2Viewer to view Html Help 2.x files.
I use NDoc3
Related
Does anyone know if there exists a Visual Studio(2010) addin/plugin that can help with managing xml documentation comments ?
Features I'm looking for:
being able to hide/show xml comments in the code (scrolling through it makes me want to hit my laptop with a hammer)
some GUI for editing those comments and an indicator which methods/classes are already documented - like an icon/color change/sth
make it easy to build documentation eg. html/pdf/...
anything else that can help
I'm not sure if this question fits on Stackoverflow, but I wasn't able to find a more suitable Stackexchange site for this and since questions can be moved between sites please move it if it's not in the right place.
I use GhostDoc to help write the comments and SandCastle (w/ Sandcastle Help File Builder as the GUI frontend) to generate html documents from the xml comments.
I know some of the tutorials for creating Xcode project templates, for example this one here: http://robnapier.net/blog/project-templates-364
This is the best one I could find. All others basically repeat the same info, or are no longer up to date, or worse tell me that even they don't know what they're doing. Possibly useful tools that are linked to here and in other places are no longer available.
I keep running into roadblocks, and would like to gather as much information as possible on the process of creating Xcode project templates. Info that is most importantly up to date (at least it must be relevant for Xcode 3 or higher).
For example, what I'd like to see is:
a description of the
TemplateChooser.plist and similar
plist files and what these options do
(in my case, once I add a
TemplateChooser.plist, my project
disappears from the Xcode project
template list)
how to create a project template that references another .xcodeproj (when I do that, the other .xcodeproj appears in the project template list even though it doesn't use the special naming convention)
processes that can be applied, for example is it possible to run a script during the creating of a project from a template? This would be useful to unzip certain files into the newly created project.
If you have the answer or suggestions to any of the issues above, I'd appreciate that. Otherwise any link to good Xcode project template resources would be highly recommended. Especially if there is an official documentation from Apple - I haven't found one yet which seems to imply that project templates are undocumented.
Have you seen these:
http://www.sodeso.nl/?p=895
http://www.codeproject.com/KB/iPhone/CreatingXcodeProject.aspx
If you say you have searched, I'm pretty sure you've already seen the links but these are the best resources I could find with my 'googlabilities'
You might try contact this guy - http://linkedin.com/in/mottishneor he has some related messages around the web
The links suggested by FX are also not bad at all!
There is indeed little XCode template info out there. What I have found of interest are the following links (I documented myself on the topic, but haven't yet gone any further):
a Google Code search reveals a few examples, but not much
in particular, I found interesting to look at the code provided by Three20; they have some basic examples, like here
referencing another project worked for me, so maybe you could open a specific question about that giving more details?
there is information scattered on the Apple mailing-lists
there is no official documentation from Apple, as is evidenced by the lack of results to this query
I'm sorry if this is not a Enlighting, concise answer. As you said, it's not well documented, and sources are all over the place. I just hope I could highlight some places to find information that your own searches might not have reached :)
I don't have a Mac anymore, so this is as much as I can give you without testing this myself. As far as I can tell, Xcode templates are undocumented by Apple.
This guy has some guides for messing with Xcode templates but the info is pretty sparse. My suggestion for working with templateChooser.plist is to try to only edit that file in the interface builder.
This guide is a good example of how to add a reference to another .xcodeproj. For the reason you were having trouble adding a reference to your project we probably need more information.
If you scroll way down in this doc you can that each template already includes a script called myscript.sh. This script will show up in the scripts menu for projects built with that template. That isn't quite as convenient as running scripts automatically, but it's better than nothing.
In conclusion, Xcode template documentation is a nightmare. It looks like there are a lot of powerful features there, but they are obscured because of lack of user friendlyness and because documentation lags far behind Apples updates of Xcode. It just doesn't seem to be a priority for them. I hope this helps.
And yet another video link http://howtomakeiphoneapps.com/2010/10/how-to-make-custom-xcode-templates-with-video/
We have a very old application dating back to ASP era which we are gradually refactoring to ASP.NET + VB.NET codebase.
It contains a lots of files with the below types:
aspx, asmx, ascx, vb, js (JavaScript), html, vbs (VBScript).
The backend database is SQL Server 2005 with lots of sprocs.
We would like to create a code documentation automatically generated from the comments in the code files. I liked Doxygen very much but seems like it does not support the above technologies. Can you please suggest some document generator tools, preferably a single tool or a group of tools?
Thanks a lot.
Ajit.
You can take a look at Microsoft's Sandcastle tool. I've used it many times, and it generates documentation based on the comments provided in your .NET code. If I remember correctly, it can also generate documentation for JavaScript libraries.
There are some out there:
SandCastle
NDOC
i've used SandCastle and it works too good if you have xml comments in your code.
You first enable xml documentation in your project by setting it in Project Properties -> Compile -> Generate XML Documentation.
Once done you may have to set treat warnings as errors, so that the studio can point out to you where and all the XML comments are missing.
To add an XML Comment, you place your cursor before a class definition or a function definition and type
///
This will automatically generate xml tags for documentation and then once you are done, you can import the project and start to build the documentation.
The good part is, if you have documented your classes well, when you use those functions in your application upon mouse over you can find the description which you wrote, much like how intellisense documentation works.
Let me know if you run into any other issues.
My last suggestion, make a hello world project and xml document it and get used to sandcastle with it.
For months now I've been trying to find a code syntax formatting extension that works for BlogEngine.Net. I'm not fond of the behavior of the default formatting extension, and have tried a couple of others (manoli is among them), but they always seem to interact badly with the TinyMCE editor. Does anyone know of an extension that works, or a different approach that will allow me to make code samples pretty on my blog without hacking the crap out of the HTML myself?
Thanks.
I would try using Windows Live Writer along w/ the Paste From Visual Studio plugin. One you go WLW, you'll never go back to that damn TinyMCE interface.
WLW here:
http://get.live.com/writer/overview
Plugin here:
http://gallery.live.com/liveItemDetail.aspx?li=d8835a5e-28da-4242-82eb-e1a006b083b9&l=8
Thanks, Rafe. Thanks to this post that Hanselman put up the day after I asked the question, I downloaded WLW and am now using it. As far as getting prettily formatted code, I'm using cut-and-paste from a little tool developed and available on manoli.net.
Check out SyntaxHighlighter.. Works excellent. For easy integration into BlogEngine have a look at my blog post.
Does anybody use the Class Designer much in Visual Studio?
I have downloaded the Modeling Power Toys for 2005 and have been impressed with what I've seen so far. The MSDN Class Designer Blog doesn't seem to have been updated for a while but it still looks quite useful.
Is the Class Designer a quick way to build the basic application or should I just work out on paper and then start coding?
Thanks
As a visualization tool, or for exploratory purposes (drawing up multiple options to see what they look like) it's not bad, but generally I find the object browser does fine for most stuff I care about.
As a code generation tool, it's a terrible idea.
The whole idea that we will design all our code structure first, then fill in the blanks with small bits of implementation is fundamentally broken.
The only time you actually know what the code structure should look like, is if you've done the exact same thing before - however then you can just use your previous code, and you don't need to draw up any new code in any kind of designer.
If you decide ahead of time to use a particular class structure before you've actually tried to solve the problem, there is a 100% chance that you will pick the wrong design, and shoot yourself in the foot.
Short answer: No.
Longer answer: No, not at all. There's a reason it hasn't been updated.
[EDIT] # MrBrutal - Sorry - do you mean to generate code or just represent a design? Because I took your question as to generate code for you.
I guess this is old, but I use it a lot. It could definitely be improved, but I find it extremely useful to be able to visualize my class structure, and to be able to jump to a specific class or method by clicking on it visually.
It's also slightly easier to add classes/interfaces with than the solution explorer, although the new files always end up in the root folder, instead of the same folder as the CD.
The main benefit I find is to be able to see a group of closely related classes at once. I think the best approach might be to have a single CD for each code folder/namespace.
I've used it a couple of times to get some decent looking class diagrams to put in presentations/blogposts etc. But thats about it...
Any suggestions on other simple UML/class diagram tools that is easy to use and create some nice looking diagrams? Must be able to generate diagrams from .NET code.
I have tried it out couple of times, mainly for viewing existing classes.
If it would show all the relationships, it would be more usefull. Now it only shows inheritation.
I find it useful sometimes, more often for documentation afterwards.
It's a new little utility, but I don't think you get the full functionality in VS Pro - I think you need Architect's Edition.
The comments here suggest that few people find the class designer useful.
Amusing to note that Microsoft designed the class designer to be a useful replacement to useless UML (UML diagrams being untrustworthy once they lose synchronisation with source code).
The trouble with class diagrams is that they tell us what we already know.
I only use the class designer to display my existing classes, but I don't use it the other way, e.g., design your classes there then let it generate the code.