C++ help with extending shfb

Topics: Developer Forum
Apr 28, 2009 at 11:30 PM
Okay, I've long wanted to get my C++ XML class documentation lifted into Sandcastle. 

Doxygen does just fine, although I don't like the layout.

With the Conceptual documents ability, it seems that I could traverse the C++ XML doc and generate a collection of Conceptual documents that replicate the docs generated from the CLR XML docs.

But, before doing this, I thought I'd ask around for the best way, as a lot of components already exist in the SHFB project, and I'm sure some of them will greatly assist.

Do you think Sandcastle will ever go "exclusively Conceptual" ?

--Ken
Coordinator
Apr 29, 2009 at 3:59 PM
I assume you are talking about unmanaged code since Sandcastle can produce documentation off of the managed C++ assemblies and XML comments files.  I'm not aware of any plug-ins for SHFB that will do what you want with unmanaged C++.  There is one for XSL schemas which takes the schema and converts it to conceptual topics (http://xsddoc.codeplex.com/).  It might give you an idea of how to make a start.  I don't know what you mean by Sandcastle going "exclusively conceptual".

Eric
Apr 29, 2009 at 11:04 PM
Thanks Eric, I'm about to take a look at it. 

Yes, I'm talking about grunt C++ code.

 ---  I don't know what you mean by Sandcastle going "exclusively conceptual".

Well, let's just say I'm making an assumption.  

The Conceptual Content looks like an abstraction of the individual docs produced from Help Compiler.  Meaning, of course, that the Help Compiler COULD be producing Conceptual Content only and then the final documentation would be built from that.  I'm not saying it is practical, just possible.  For instance an Enumeration type in the code docs could produce a Conceptual Content file with the appropriate block elements, in-line elements, etc.

Of course, what I would call the "Help Compiler" might not be correct, as it is an entire pipeline, but I think you understand.

<aside>
I hate this terminology though, why does straight C++ have to be qualifed as "unmanaged"? It totally casts a negative image on the language.  Why isn't C++/CLI called "managed"?  It seems that C++ earned it's title before C++/CLI.  And I don't think anybody uses the Visual Studio 2003 MC++ anymore, anyway -- too buggy with "undeterministic failures" in the loader.

You know, my old company was doing the "UCOM" and "U" this and "U" that to refer to the old obsolete dinosaur code where you had to actually remember to keep track of the objects you created and knew what you were doing.  That was until Microsoft dropped the "U" prefix between 2003 and 2005 Studio releases.
</aside>
Coordinator
Apr 30, 2009 at 8:18 PM
Edited Apr 30, 2009 at 8:19 PM
BuildAssembler converts the XML comments and reflection information directly to HTML using XSL transformations.  It also converts MAML (conceptual content) to HTML using many of the same XSL transformations so I doubt there would be any reason to convert the XML comments/reflection info to MAML prior to going to HTML.

Regarding documenting straight C++, it would probably make more sense to create a tool that produced a reflection information file based on the C++ API similar to what MRefBuilder does for managed assemblies.  That's what AjaxDoc does to produce documentation for JavaScript.  Once you get the reflection file, the rest of the process would be the same and you wouldn't have to do anything related to producing MAML for the API topics since it would all go straight to HTML just like it normally does.  As I recall, this has come up a couple of times in the past but so far nobody has released anything that I know of that will do it.

Eric
Apr 30, 2009 at 11:35 PM
Thanks again.

I'll look at the AjaxDoc.  The XML docs from the straight C++ compile ALMOST work. 

The issue, that I recalled from months ago was that the mrefbuilder didn't have anything to reflect and I didn't know where to go from there.
The AjaxDoc probably would be a good basis for discovery.

I was a bit confused about the MAML pipeline though.  It wasn't clear how the Plug-Ins and Build Components in SHFB interacted with MAML.  As I now understand it, things like the Post Transform and Code Block, etc still get executed on the MAML docs.

( I saw a comment stating it was better to use the Code Block Component rather than the Code Snippets file and it didn't make sense until I actually tried it ).

If I get anything working, I'll ping back with updates for anybody else that might be interested.

--Ken