link conceptual help with code sample

Topics: User Forum
Jul 17, 2008 at 4:26 PM
Hello,

I have just discovered MAML this morning (while installing the latest version of Sandcastle).
I did immediately some tests to add some "conceptual topics" into my generated documentation and have now plenty of questions.

May I ask here the one that is the most important for me ?

I really appreciate the attribute "source" that can be used in the code tag of xmldoc since it's supported by SHFB.
I.E..: <code source="Dummy.Sample\Dummy.cs" region="Dummy Code Sample" lang="cs" title="Dummy Service usage" />

The highest added value of this attribute is that the generated documentation only contains code samples that compile.
In addition, if this code could actually comes from unit tests, we are sure that it run fines and that the documentation if fully up-to-date.
This is great for the maintenance budget.

Now, I intend to use conceptual topics to write some how-to's and walktroughs.
I would also appreciate to reuse actual code in the examples of those documents.
Unfortunately, I don't see any MAML tag that could be used to reference regions in classes of my projects...

Am I missing something ? Or there is really no way to do this ?

If there is no such tag, then I will have to manually check that the examples are up-to-date in all my conceptual topics.
And for sure, that's not good for the maintenance budget!

Thx in advance for any answer.

Valéry.
Coordinator
Jul 17, 2008 at 8:28 PM
Hi Valéry,

MAML topics also support the <code> tag.  The Code Block Component supplied with SHFB is also useable in conceptual topics and is included in the build by default so all of the same extended attributes apply and it will recognize either the "language" or "lang" attribute to specify the language.  As such, you can add <code> tags just like you do in XML comments and the code will be imported and colorized in the same way.

If you aren't familiar with MAML, check out the MAML Guide which is available at the Sandcastle Styles project site.  It covers all of the basic elements and should get you up to speed.

Eric
Jul 18, 2008 at 8:30 AM
Edited Jul 18, 2008 at 10:51 AM
Thanks a lot !

I have been reading this guide previously (the <code> block element) but didn't notice explicitly that the same attributes could be used both in the xml doc and in the conceptual help.
I should have tried before asking you, sorry :/

That being said, it really works like a charm for a simple <code> element. I have just "copy-pasted" the <code> block element from my xml doc (I.e.: from the comment of my class) into my conceptual topic and that's it. Just for information (for other readers), I was hesitating about the path to be used in the source attribute. But the same path can be used both in the xmldoc and in the conceptual help as it is relative to the .shfb file, not relative to the class or to the conceptual topic's file. That's great as I really just have to copy/paste the block from a class into the conceptual topic. I should maybe just search a solution to avoid this copy/paste (for maintenance reasons) and share a common content....

Now, I notice that the usage of nested <code> blocks does not work fine. I have used the following block both in my xml doc and in my conceptual topic:
    <code lang="xml" title="How-to configure the Dummy Service">
        <code source="Dummy.Labs\Web.config" region="Dummy configSection"/>
        <code source="Dummy.Labs\Web.config" region="Dummy section"/>
    </code>

From the xmldoc, shfb generates the right documentation:
<section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
<dummy name="Dummy" value="Hello World"/>

From the conceptual topic, it generates:
<code source="Dummy.Labs\Web.config" region="Dummy configSection" xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" />
<
code source="Dummy.Labs\Web.config" region="Dummy section" xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" />

Do I am missing something ?

V.
Coordinator
Jul 18, 2008 at 4:26 PM

There's a bug with regard to nested code blocks in conceptual content.  I haven't had a chance to look into it yet.  I'll open a work item and attach the fix to it when I have.

Eric