Getting the DXA API documentation to display in Visual Studio
Today I was looking for the documentation for the API of the SDL Digital Experience Accelerator. I’d hoped to find a CHM or something similar so that I could quickly make reference to the documentation of the methods and properties as I used them. When I looked at the source code of the framework, I could see that the developers have documented the methods using XML comments, so the hard part was already done, so it seemed a shame that it wasn’t easy to use. My next step was to go to Tridion Stack Exchange, and ask a question there. Pretty soon, I had a response saying that the idea is to use the data from the XML comments via the automatic display in Visual Studio.
Unfortunately, the only information you get this way is what is available from the metadata of the assembly, so you get the method signature, but not much else. I hope this will be addressed in a future release of DXA, but in the meantime, it’s pretty easy to fix it yourself, so here’s how:
First download the source code of the framework itself by cloning the repository at https://github.com/sdl/dxa-web-application-dotnet. Open up the DxaFramework solution, and locate the build properties tab of the projects you want “intellisense” documentation for. For example, here is a screen capture of the build propeties for Sdl.Web.Mvc:
Check the check box for XML documentation file. It should default to the correct name, matching the name of the assembly. (For me it seemed to work better if I changed this to ensure that the “xml” extension was in lower case. YMMV)
After you’ve done this and built the solution, go to the bin directory and copy the resulting XML files. Go to the project where you are developing your DXA application and paste them next to the matching assemblies in your Site/bin directory.
Once you’ve done this (I also restarted Visual Studio, but I’m not sure if it’s necessary) you should find that the summary is displayed when you hover over a method, and that the full API documentation is displayed in-line when you use F12 to “Go to Definition”. Here’s a screen capture of what you see if you do that for VersionedContent (after opening the collapsed region). You’ll also see more information when you add parameters.
This is definitely something you should do early on in your project. It’s really useful to have this information at your fingertips.