XML documentation in unmanaged C++

[Bob Altman]

I thought I read somewhere in the MS documentation that XML documentation is
compiled in C++, but the C++ code editor obviously doesn't do anything
interesting when I enter "///". What's the deal with C++ and XML docs? Is
there an add-in available to help with entering XML docs?

TIA - Bob

 

[Gary Chang[MSFT]]

Hi Bob,

The VC2005 compiler supports the XML documentation comment, it could
generate the XML file from your code comments (which are prefixed by
'///')). But it would not support the "on-the-fly" XML comments. You need
to compile it and then it should support it. Please refer to the following
blog article for the details:

http://blogs.msdn.com/peterhu/archive/2004/05/05/126767.aspx

"Support for XML doc comments: we now support XML doc comments in compiled
files. The compiler outputs an .xdc file which contains the documentation
information fragments. There's a new tool called xdcmake which takes these
fragments and produces the final .xml comments file. This tool is
integrated into the IDE, so producing doc comments is as simple as enabling
the /doc switch in the compiler's property pages (the xdcmake tool
automatically runs when the compiler outputs .xdc files). In addition,
IntelliSense will support these xml comment files. "

I suggest you can also refer to the related MSDN documentation for the
usage of XML documentation comment in VC2005:

XML Documentation (Visual C++)
http://msdn2.microsoft.com/en-us/library/ms177226.aspx

doc (Process Documentation Comments) (C/C++)
http://msdn2.microsoft.com/en-us/library/ms173501.aspx

XML Document Generator Tool Property Pages
http://msdn2.microsoft.com/en-us/library/ms235515.aspx

I hope the above information helps, if you have any questions or concerns,
please do not hesitate to let me know. I am standing by to help you.

Thansk!

Best regards,

Gary Chang
Microsoft Online Community Support
==================================================
Get notification to my posts through email? Please refer to
http://msdn.microsoft.com/subscriptions/managednewsgroups/default.aspx#notif
ications.

Note: The MSDN Managed Newsgroup support offering is for non-urgent issues
where an initial response from the community or a Microsoft Support
Engineer within 1 business day is acceptable. Please note that each follow
up response may take approximately 2 business days as the support
professional working with you may need further investigation to reach the
most efficient resolution. The offering is not appropriate for situations
that require urgent, real-time or phone-based interactions or complex
project analysis and dump analysis issues. Issues of this nature are best
handled working with a dedicated Microsoft Support Engineer by contacting
Microsoft Customer Support Services (CSS) at
http://msdn.microsoft.com/subscriptions/support/default.aspx.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

 

[Bob Altman]

Hi Gary,

Based on the articles you referred me to, it's clear that the C++ compiler
will process XML documentation. But what about tools to help me create the
documentation in the code editor? In VB and C#, the code editor and
intellisense help me to correctly create XML documentation. But the C++
code editor seems to just ignore "///". Am I missing something?

- Bob

 

[Gary Chang[MSFT]]

Hi Bob,

Just as I suggested in my last post, add the /doc compiler option to your
project compilier options:

To set this compiler option in the Visual Studio development environment:

1. Open the project's Property Pages dialog box.

2. Expand the Configuration Properties node.

3. Expand the C/C++ node.

4. Select the Output Files property page.

5. Modify the Generate XML Documentation Files property.

Then after the building process, the XML comment file should be generated
in the location which you specified in the 'Output Document File' entry of
the 'XML Document Generator Tool Property Pages'


Thanks!

Best regards,

Gary Chang
Microsoft Online Community Support
==================================================
Get notification to my posts through email? Please refer to
http://msdn.microsoft.com/subscriptions/managednewsgroups/default.aspx#notif
ications.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

 

[Bob Altman]

Gary,

/doc only helps if there is XML documentation in the source code to begin
with. My original question was whether or not the IDE (the C++ code editor
and C++ intellisense) will give me any help with authoring XML documentation
the same way VB and C# do. Lacking built-in support in the VS 2005 IDE, is
there a plug-in that any readers of this NG can point me to that provides
contextual editing help for XML documentation in C++ source code.

- Bob

 

[Gary Chang[MSFT]]

Hi Bob,

My original question was whether or not the IDE (the C++ code
editor and C++ intellisense) will give me any help with authoring
XML documentation the same way VB and C# do

Sorry for misunderstanding your questions. I am afraid the VC2005 editor is
unlike the C# and VB.NET editor, it only provides some limited intellisence
after the source code have beed compiled.

Thanks!

Best regards,

Gary Chang
Microsoft Online Community Support
==================================================
Get notification to my posts through email? Please refer to
http://msdn.microsoft.com/subscriptions/managednewsgroups/default.aspx#notif
ications.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.