Sandcastle - Please consider allowing richer formatting in documentation

Hi there,

I've seen the developers behind Sandcastle seem to be very active here so I thought I may make a request - something I'm sure is wanted by others (albeit perhaps indirectly).

My employer is considering enforcing a set format for comments for each class with this information.

Class Name (covered implicitly by Sandcastle)
Description (covered by <summary>)
Date Created
Authors (possibly list)
Revision Table with these headings

Date of change
Issue reference number
Developer whom made change
Reviewer of change
Summary sentence of change made

I've argued for the fact that these things should be covered by the source repository - and they've agreed but want this stuff at the top of class headers too - as we are currently looking at migrating between repositories within the next few months.

In Visual Studio 2003 I managed to create documentation which allowed html mark-up etc, but VS 2005 Pro generates xml that although has mark-up in there, it's currently all stripped out in the Sandcastle pipeline as it stands.

I've looked in to using <list type="table"> for the revision table and that didn't seem to work. I've tried normal html which is stripped out.

I was wondering - as Sandcastle seems to be based on xslts and translations, how possible it would be to have custom mark-up and use a custom xslt during the process that transforms things. So that say:

<revisionTable>
<revision>
<date>20060824</date>
<issueRef>#xyz123</issueRef>
<developer>Paul</developer>
<reviewer>Kev</reviewer>
<summary>Created file</summary>
</revision>
<revisionTable>

... could be translated by our own xslt in to html mark-up or something.

Also letting us set attributes such as the css class <date CssClass="date">20060825</date> could be useful during a transform to allow the html view at least to use css sheets.

Supporting custom xml tags in xslts would also allow us to target two different types of documentation - internal documentation with all the revisions etc with the classes - and external documentation with that information omited via a different xslt.

Right now though I would settle for anything that allowed me to create tables with as many columns and custom headings as I would like. So if there is a way to do some of this and I've just not found it out yet please let me know!

Thanks for your time,

Paul

Answer this question