Sandcastle, /doc, and Unmanaged C++ - visual-c++

I work on a project that uses unmanaged visual C++ and a smattering of C#. We are trying to come up with a way to document our project, both the API reference, as well as some additional conceptual documents. Ideally, all of the documentation would live together in a .chm file that we could distribute with our product.
I was already familiar with Doxygen, as a long time C++ developer. Someone suggested that I look into Sandcastle as well, but I've run into a few snags.
From a number of other sources, including other posts on this site, it's well known that sandcastle does not support unmanaged C++. I did find a post that seems to indicate that you can still cram the C++ documentation into sandcastle, by adding the API reference as conceptual topics.
Using Visual Studio 2010, you can turn on the /doc option in the project settings for your unmanaged C++ project. This produces .XDC files which studio then compiles into an .xml file that goes along with your lib/dll/exe. Where I am stuck is that is unclear what exactly you can do with this xml file. Some pages I've found online suggest that you may be able to use this file for intellisense, but I've never seen that work in unmanaged C++. I was hopeful that I might be able to use this .xml file in Sandcastle Help File Builder somehow, but I can't find any examples of how that's done online, and every attempt I've made with SHFB has failed. It seems to only want MAML or HTML files if I want to add an existing conceptual help file.
So my question:
Is there a way to get my /doc generated .xml file into my SHFB help solution?
If not, what is the point of the /doc option for unmanaged C++?
Is there some kind of transformation I can do on my /doc generated .xml file to produce HTML or MAML which I could then import via SHFB?
Can this work, or should I just go back to Doxygen?

In theory, Sandcastle could be used to document unmanaged code but it would require a tool to produce the equivalent reflection data file that is currently produced by the MRefBuilder.exe tool for managed code assemblies. So far, nobody has done that to my knowledge.
I can't comment on the lack of IntelliSense for unmanged C++ since I don't use it anymore. At a guess, /doc is probably there for the managed code output assuming the same compiler is used but with a few extra command line options.
Using XSL to transform the XML comments to MAML is a possibility but, again, it's an option I'm not aware of anyone pursuing. My guess is that most opt to use Doxygen in this case since it's an established solution.
Eric

I have a similar situation. I need XML documentation in my C++/CLI bindings so .NET code can see them with Intellisense. But FYI, Visual Studio 2010 doesn't support XML documentation in native code:
https://msdn.microsoft.com/en-us/library/ms177226(v=vs.100).aspx
Visual Studio 2010
In Visual C++, you can add XML
documentation (triple-slash) comments to your source code and instruct
the compiler to output them to an .xml file. This file can then be
input to a process that creates documentation for the classes in your
code. The IDE for Visual C++ in this version does not support XML
comments in Intellisense.
That limitation was removed in Visual Studio 2013. However, it's still an annoying ecosystem to work with if you use templates in the native code (e.g. Boost libraries):
In the current release, code comments are not processed on templates or anything containing a template type (for example, a function taking a parameter as a template). Adding such comments will result in undefined behavior.
I found your question while searching for a way to temporarily disable the XML comment parser with a #pragma or #define when including such libraries.

Related

How are project interdependencies managed in MS Visual C++?

Probably a pretty fundamental question. When developing a single-project-solution in MSVC++ everything makes a lot of sense, every file is visible to the compiler. When moving to a multiple project solution, none of the interface elements governing project dependence seem to make sense (coming from a .net background.)
For starters it appears setting up project dependencies with that terminology seems to only imply what order the projects are compiled in. There is no more function attached to the definition and addressing objects or methods of one project from another will not work. #including the headers of the dependency doesn't seem to work either, so the dependent project cannot see the files of its dependency. Copying a link of a header from one project to another doesn't work either, where for two projects under the 'Header Files' section, the same file is referenced in both locations. Even with this header references do not work and the files are unconnected. The only way of creating a functional dependency is to add the dependency's paths to the linker/compiler search path of the dependent or worse, simply copying the files of one project to another.
Either I'm missing something or the .NET Visual Studio IDEs have succeeded at what the VC++ IDE has badly failed at.
Edit:
For the sake of asking a specific question, take the following steps for creating a solution in VC++ and I ask if the missing step(s) can be filled in:
Create empty DLL project inside new solution.
Create method in DLL project and compile.
Create new empty executable project.
Create main method in new project.
...
Have main method call function in DLL project.
Preferably fill in the missing step(s) with the most most modern/industry standard/best practice method that best maintains project modularity as intended.
From this I would expect to independently be able to extrapolate and create classes, enumerations etc. in the DLL class and access them all in the executable project, so long as I can find out how this is intended to be done.
In step 2, as per the usual C++ rules, declare the method in the header. Read up on __declspec(DllExport) since the default is that methods are internal to the DLL.
In step 5, as per the usual C++ rules, include the header. Visual C++ needs to know where the header is coming from, so you need to reference the source project. Details vary between Visual Studio versions.
In step 6, you call the method in the normal way. Since it's now declared as __declspec(DllImport), the compiler will leave it to the linker, and the linker will get it from the correct DLL.

Visual Studio 2008 Read values from XSD file

First post. I am trying to read the values of any XSD in Visual Basic. I want the application to read back values like complextypes, elements etc. I have been looking at MSXML2 but most examples include validation against a XML file. I only want to read XSD and get information. Will xml reader be able to read a XSD file? Any help be great.
It depends a lot on what you're trying to do with this information, therefore the prerequisites you need to have in place before doing it.
For all but really trivial tasks, I recommend the use of classes in System.Xml.Schema namespace, particularly start with XmlSchema and XmlSchemaSet. This would allow you to manipulate XSDs any way you want; it would also allow you to validate the schemas before using them, if it would prove to be a requirement.
For completeness, and for what I would call very simple tasks, you may also think that XSD is just XML, so then any XML processor should allow you to load an XSD and interogate it as needed.
All of the above, since you've mentioned VS2008, would be on Visual Basic.NET. If you're still on Visual Basic and need to rely on MSXML, then I would refer you to this article on using Visual Basic and SOM.

Parsing Excel files in monotouch

Are there any good ways of parsing Excel files in monotouch? Seems like most methods to work with Excel is based on using the Excel Object Library. Doesn't seem like that's even an option in monotouch? I read that objective-c doesn't have any native support for Excel-files, so don't know if that would change anything?
You would need to either
write your own
find an obj-c library that does it and write MT bindings for it
find a open source .NET library and port it to MT
If all you want to do is display a file, you can use the existing iOS document APIs to do it.
The newest Office formats are XML based, so depending on how complex the files are, writing your own parser might be feasible to do.
I ended up just writing the middle step, a web service that fetches the Excel file, parses it and serves up the content as xml/json.

enabling XML comments in C++ in Visual Studio 2010

How can one enable/achieve XML comments for C++ methods ala C# and VB in Visual Studio 2010? It appears this functionality isn't enabled/available by default.
Targeting initially managed C++ projects.
Configuration Properties -> C/C++ -> Output Files -> Generate XML Documentation Files.
You will have to manually add all your xml documentation (/// doesn't auto-create a summary template for you). Also doesn't support paramref. http://msdn.microsoft.com/en-us/library/ms173501.aspx
To auto complete xml documentation stubs when /// is typed try CppTripleSlash - xml doc comments for c++ extension. It also has some basic intellisense to complete xml tags inside doc comments.
I know this is the old one, but everywhere I have looked everyone say's NOT SUPPORTED, need 3rd party tool or similar, none which is not the true. What you need to know is that XML Documentation is supported and is available in Visual Studio 2010, and there are only two things to know about it:
Docs/Previous Versions / Visual Studio / XML Documentation / Recommended Tags for Documentation Comments:
https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2012/ms177227%28v%3dvs.90%29
In "C++ project properties / C/C++ / Output Files / Generate XML Documentation Files" set to "Yes (/doc)"
It will generate .xdc file for each source file containing documentation comments "///" and merge it into one .xml documentation file. And documentation works just fine later in other projects.
This is not supported in C++ for VS2010.

What information about me and my system do compilers add to executeables?

I'm currently using Microsoft Visual Studio 2010.
If we say that we give 10 different people a copy of MSVC 10 and a short C++ Hello, World listing. They all create a new project using exactly the same settings, add a new cpp file with the Hello, World program and compile it.
Do they all get the exactly same binary?
If not, what are the exact differences?
What information about my system does MSVC add to my executeable?
Paranoia!
If you each create a project from scratch you'll at least get different GUIDs assuming it's the type of project that needs GUIDs. The GUID is set at the time you create the project so if one of you creates the project and then you share the project there will be no difference in the binaries. There is no identifiable info in the GUIDs AFAIK.
Just can't help to respond even though the question is more than a year old.
Apart from what was already mentioned (source paths & guid), there is also a structure present in most Portable Executable file known as the Rich Header.
More detailed info can be found at the following links:
http://ntcore.com/files/richsign.htm
http://web17.webbpro.de/index.php?page=microsofts-rich-header
As far as I know you would get the exact same binary...

Resources