When will unmanged C++ documentation be supported?

Feb 22, 2008 at 2:42 PM
I have a static unmanaged C++ library with documentation comments that I would like to produce docs for :)
A prior release note mentioned that version 2.0 of Sandcastle would provide a mechanism for generating reflection xml by parsing C++ headers, or equivalent. Has this functionality been scheduled yet?
Thanks.
Feb 23, 2008 at 9:33 AM

dwhobrey wrote:
I have a static unmanaged C++ library with documentation comments that I would like to produce docs for :)

Have you tried Doxygen http://www.stack.nl/~dimitri/doxygen/

Best regards,
Paul
Feb 23, 2008 at 2:38 PM
Hi Paul,
i've been using doxygen as an interim - i think it's pretty good. The project was originally managed C++ and I had a SHFB project set up with additional content that SHFB turned into a nice chm, so being lazy, i wanted to reuse this content. However, having been using doxygen for the past couple of months, I'm now considering converting the additional content to DocBook, which would make the docs more portable.
Regards, Darren.
Feb 23, 2008 at 4:07 PM
Hi,

Instead of DocBook, have you considered using Sandcastle's support for conceptual documentation? It uses Microsoft Assistance Markup Language (MAML), which is structured authoring so it's more portable than HTML.

- Dave
Mar 5, 2008 at 9:47 AM
Thanks for the pointer to MAML. Once Sandcastle can handle unmanaged C++ comments, that and MAML will make it a very convenient help builder - not having to worry about layout is a relief. Meanwhile, since I already had the userguide, in html, and api docs set up for use with SHFB, I'm now using doxygen to generate the api docs and have a little script to integrate this into the userguide website and chm. This is not ideal, since i don't have complete control of the doxygen api doc layout - i can change the doxygen css, but for present purposes it's good enough. A big plus, though, is that it is portable - and the docs can be produced without compiling the code.
Regards, Darren.
Feb 26, 2009 at 7:24 AM
Any update on the support of Unmanaged C++ in future versions of SC?
Feb 26, 2009 at 7:48 AM
>>goloroden: Any update on the support of Unmanaged C++ in future versions of SC?
By its title, Sandcastle - Documentation Compiler for Managed Class Libraries, so there is no official plan I know off.
Individuals may be working on something, but none is announced, so you will be better off using the Doxygen.

Best regards,
Paul.

Feb 26, 2009 at 8:34 AM

Hi,

I haven’t been chasing this since I’m managing with doxygen. It’s a shame that more effort isn’t being put into incorporating unmanaged C++ within Sandcastle – the effort wouldn’t be that great and I would have thought there was a reasonable demand for documenting MS C++! You could try chasing the prior announcement that version 2.0 of Sandcastle would have a mechanism for extracting reflection xml from unmanaged C++. I saw that there is an open C++ parser that can produce this kind of info, although it would need some translation. It would make a nice third year university project for an interested Computer Science student. J

Regards,

Darren.

From: goloroden [mailto:notifications@codeplex.com]
Sent: 26 February 2009 08:25
To: d.whobrey@mildai.org
Subject: Re: When will unmanged C++ documentation be supported? [Sandcastle:22668]

From: goloroden

Any update on the support of Unmanaged C++ in future versions of SC?

Read the full discussion online.

To add a post to this discussion, reply to this email (Sandcastle@discussions.codeplex.com)

To start a new discussion for this project, email Sandcastle@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com

Feb 26, 2009 at 8:55 AM

Hi Paul,

Has the title always been this? I remember when SC first came out the claims were more general for its scope, and in the official release notes there was talk of supporting unmanaged C++ from version 2.0? I’m curious as to what MS’s recommendation is on documenting unmanaged C++? My apologies here for being out of touch with the current aims.

Regards,

Darren.  

From: SelormeyPaul [mailto:notifications@codeplex.com]
Sent: 26 February 2009 08:48
To: d.whobrey@mildai.org
Subject: Re: When will unmanged C++ documentation be supported? [Sandcastle:22668]

From: SelormeyPaul

>>goloroden: Any update on the support of Unmanaged C++ in future versions of SC?
By its title, Sandcastle - Documentation Compiler for Managed Class Libraries, so there is no official plan I know off.
Individuals may be working on something, but none is announced, so you will be better off using the Doxygen.

Best regards,
Paul.

Read the full discussion online.

To add a post to this discussion, reply to this email (Sandcastle@discussions.codeplex.com)

To start a new discussion for this project, email Sandcastle@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com

Feb 26, 2009 at 9:12 AM
Edited Feb 26, 2009 at 9:13 AM
Hm. By pointing to the title you simplify everything a little bit too much, don't you think so?

I also remember that it was originally said that 2.0 is going to support unmanaged C++, and actually there are still lots of lega-C++ code out there, so it would be real nice if something like this could be done.

BTW: Anyone, who is interested in this feature, too, should vote at http://www.codeplex.com/Sandcastle/WorkItem/View.aspx?WorkItemId=3855
Feb 26, 2009 at 9:33 AM
>>Darren: Has the title always been this?
Probably not, but the notes always imply this.

>>Darren: ...official release notes there was talk of supporting unmanaged C++ from version 2.0?
I might have missed that. Most of us came to Sandcastle from NDoc, and Unmanaged C++ was not a target.

>>Darren: I’m curious as to what MS’s recommendation is on documenting unmanaged C++?
Hmmm, should there be? Creating a C++ compiler and an IDE does not add a responsibility to provide a
free documentation tool, especially where the documentation method is not part of the C++ specifications.
 
I think you need to be a little realistic. Sandcastle was an internal MS documentation tool, which was made
public, and we should be very grateful for this. They are paying those working on it, and if there is no gain
on their investment, then there is no practical reason for it. And in this time of economic crisis, MS is not
left out.

I started Sandcastle Assist to extend  and enhance the Sandcastle. C++ support through Doxygen could be added,
but we already have enough work to do, and cannot make any commitment at this stage. You and others could help
such efforts with at least feedback and testing, if you need them fast.

Best regards,
Paul.
Feb 26, 2009 at 10:01 AM

This does make me wonder what kind of documentation process MS follows for their unmanaged C and C++. It’s also been a long time since product development was merely about producing a compiler and IDE that solely conformed to an industry standard. MS itself encourages good development practices that nowadays entails documenting standards as well. If SC is not the place for unmanaged documentation, and some other tool is, then maintaining systems with modules written in different languages from the C family becomes awkward, for example, because of divergence in documenting standards between the tools.

If only a shining star on the MSVC team could add a project option to the compiler to generate the required xml life would be simpler for some …

From: goloroden [mailto:notifications@codeplex.com]
Sent: 26 February 2009 10:12
To: d.whobrey@mildai.org
Subject: Re: When will unmanged C++ documentation be supported? [Sandcastle:22668]

From: goloroden

Hm. By pointing to the title you simplify everything a little bit too much, don't you think so?

I also remember that it was originally said that 2.0 is going to support unmanaged C++, and actually there are still lots of lega-C++ code out there, so it would be real nice if something like this could be done.

Read the full discussion online.

To add a post to this discussion, reply to this email (Sandcastle@discussions.codeplex.com)

To start a new discussion for this project, email Sandcastle@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com

Feb 26, 2009 at 10:29 AM
>>DarrenThis does make me wonder what kind of documentation process MS follows for their unmanaged C and C++.
As said by a member of the Documentation Team, they do not use the XML Docs as we do from our codes.
Here is a picture...
http://blogs.msdn.com/sandcastle/archive/2006/12/06/a-microsoft-code-name-a-day-sandcastle.aspx

Also, if you take a close look at the C/C++ documentations in the MSDN, you will notice that it was done as
conceptual reference help. So, my guess  is they have a system for maintaining their documentations (may be DocStudio),
and generates the conceptual topics for C/C++ and reference XML for the managed system, which is then compiled
by the Sandcastle to the MSDN output.

You may also take a note of the last item in the first introduction Sandcastle
http://blogs.msdn.com/sandcastle/archive/2006/07/27/680793.aspx

Best regards,
Paul.
Feb 26, 2009 at 10:53 AM

Hi Paul,

Thanks for the info. It’ll be interesting to see what direction documentation takes over the next few years - in terms of standards, cross language support, platform, etc., especially now that MS is supporting cloud services and all this implies in terms of service integration and performance coding for parallel systems, which might dictate unmanaged C or C++ modules – and even Fortran (let’s not worry about Cobol anymore). J

Regards,

Darren.

From: SelormeyPaul [mailto:notifications@codeplex.com]
Sent: 26 February 2009 11:29
To: d.whobrey@mildai.org
Subject: Re: When will unmanged C++ documentation be supported? [Sandcastle:22668]

From: SelormeyPaul

>>Darren: This does make me wonder what kind of documentation process MS follows for their unmanaged C and C++.
As said by a member of the Documentation Team, they do not use the XML Docs as we do from our codes.
Here is a picture...
http://blogs.msdn.com/sandcastle/archive/2006/12/06/a-microsoft-code-name-a-day-sandcastle.aspx

Also, if you take a close look at the C/C++ documentations in the MSDN, you will notice that it was done as
conceptual reference help. So, my guess is they have a system for maintaining their documentations (may be DocStudio),
and generates the conceptual topics for C/C++ and reference XML for the managed system, which is then compiled
by the Sandcastle to the MSDN output.

You may also take a note of the last item in the first introduction Sandcastle
http://blogs.msdn.com/sandcastle/archive/2006/07/27/680793.aspx

Best regards,
Paul.

Read the full discussion online.

To add a post to this discussion, reply to this email (Sandcastle@discussions.codeplex.com)

To start a new discussion for this project, email Sandcastle@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com

Feb 26, 2009 at 11:29 AM
The point where I always get stuck and wonder is:

Is it really so hard to make the C++ compiler write the XML files and add a switch to the property page of the project?

Of course, I do not have any insight into MS' code, but I can hardly imagine that it is so extremely hard to do this (when looking at what this company does in other areas which are probably more complex ;-)).
Feb 26, 2009 at 12:02 PM
>>goloroden: The point where I always get stuck and wonder is:
Really? :) I thought you should rather be stuck and wonder why a documentation must be created only
by Sandcastle; otherwise, it is not a documentation!

Doxygen already gives you an XML files, and supports XML Doc tags in the codes. The XML format
cannot be consumed by Sandcastle, so why not take that as a sub-project to make it compatible with
Sandcastle?
Doxygen even provides a means of generating the format, so you could write an addin to directly give
you the format used by the Sandcastle and save yourself a lot of headaches.

Please, I do not think this discussion will get any result, so take action and many out there could join.
I had to take the initiative to make the Sandcastle conceptual support easy to start when it was released
without any documentation, and I wanted to use it. 
It was not as easy as it looked now, trying to make sense of the various files and the complex schema...
http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

Best regards,
Paul.
Feb 27, 2009 at 8:50 AM
Hi Paul,

of course, you can use any other tool to build your docs, but I do not want to have several tools which need to be integrated, and which increases dependencies from different vendors. I would expect that a tool from vendor A does support all currently active languages from vendor A, especially if there was an announcement that said so.

It may be, that for you using Doxygen or any 3rd party tool is an option, for us it is not.

Regarding the initiative - I am already working on several projects, and I don't know how to get time for still another one. The point is that it can not be such a big problem for MS to provide this, and there is - to be true, and at least in my opinion - no real need for another community project.

Cheerio,


Golo
May 22, 2009 at 4:26 AM

I agree with Golo, native C++ should be supported by sandcastle natively.

Cheers,

Greg