Using para and example

Nov 5, 2007 at 7:38 AM
If I am using <para> and <example> tags in my code documentation, I miss this later on in the output of sandcastle.
Does sandcastle not support <code> or <para> tags.

For <para> I would expect that there is a line feed or something like that. Just for formatting. Without formatting the whole text is put together. That is not always good to read.
Also my <example> tag with an inner <code> tag has been totally ignored...

What is going wrong here?
Coordinator
Nov 5, 2007 at 2:58 PM
The tags you list are all supported and work fine. Can you post an example that does not work?

Eric
Nov 6, 2007 at 7:39 AM
Edited Nov 6, 2007 at 10:43 AM

You are right I had made a mistake. The para and the example work now fine, but the inner code is still ignored...

Could it be that the code is ignored because I have set the syntax filter to visual basic?
After setting the syntax filter to C# and VB I got the code...
Do I have to specify the code to be visual basic code? Is that possible at all?

Can I use <see cref=""></see> constructs in the code tag to reference method calls?

This is my result right now:
Examples
This example shows how to use parameters:
CopyC#
Private Function Query(das As <see cref="DAS"></see>,Param1 As String, Param2 As Integer) as <see cref="DASAccess.DASDataTable"></see>
Dim returnValue As <see cref="DASAccess.DASDataTable"></see>(das)
Const STR_Param1 As String = "@Param1"
Const STR_Param2 As String = "@Param2"
Dim sql As String = String.Format("SELECT * FROM Table t where t.col1 = {0} and t.col2 = {1}", STRParam1, STRParam2)

returnValue = new <see cref="DASAccess.DASDataTable"></see>

Try
das.<see cref="DAS.AddParameter"></see>(STRParam1, Param1, <see cref=" DAS.ParameterModes.PARMIN"></see>, <see cref="DAS.ServerTypes.ST_VARCHAR2"></see>)
das.<see cref="DAS.AddParameter"></see>(STRParam2, Param2, <see cref=" DAS.ParameterModes.PARMIN"></see>, <see cref="DAS.ServerTypes.ST_NUMBER"></see>)

das.<see cref="DAS.FillDataTable"></see>(returnValue, sql)
Finally
das.<see cref="DAS.RemoveParameter"></see>(STR_Param1)
das.<see cref="DAS.RemoveParameter"></see>(STR_Param2)
End Try

Return returnValue
End Function

Exceptions

And this is the source:

''' <example> This example shows how to use parameters:
''' <code>
''' Private Function Query(das As <see cref="DAS"></see>,Param1 As String, Param2 As Integer) as <see cref="DASAccess.DASDataTable"></see>
''' Dim returnValue As <see cref="DASAccess.DASDataTable"></see>(das)
''' Const STR_Param1 As String = "@Param1"
''' Const STR_Param2 As String = "@Param2"
''' Dim sql As String = String.Format("SELECT * FROM Table t where t.col1 = {0} and t.col2 = {1}", STRParam1, STRParam2)
'''
''' returnValue = new <see cref="DASAccess.DASDataTable"></see>
'''
''' Try
''' das.<see cref="DAS.AddParameter"></see>(STRParam1, Param1, <see cref=" DAS.ParameterModes.PARMIN"></see>, <see cref="DAS.ServerTypes.ST_VARCHAR2"></see>)
''' das.<see cref="DAS.AddParameter"></see>(STRParam2, Param2, <see cref=" DAS.ParameterModes.PARMIN"></see>, <see cref="DAS.ServerTypes.ST_NUMBER"></see>)
'''
''' das.<see cref="DAS.FillDataTable"></see>(returnValue, sql)
''' Finally
''' das.<see cref="DAS.RemoveParameter"></see>(STR_Param1)
''' das.<see cref="DAS.RemoveParameter"></see>(STR_Param2)
''' End Try
'''
''' Return returnValue
''' End Function
''' </code>
''' </example>
Coordinator
Nov 6, 2007 at 3:17 PM
Edited Nov 6, 2007 at 3:21 PM
I wasn't aware that <see> tags were valid within a <code> block. The Code Block Component colorizes the code and since it isn't aware of the tags, it converts them as part of the colorized code. As such, what you're trying to do isn't possible without removing the Code Block Component. It may be possible to support them but it would probably take quite a bit of work and isn't something I plan on looking into for a while.

Also note that the default language for the Code Block Component is C# and they blocks are connected to the language filter. As such, if your <code> blocks lack a lang="vbnet" attribute, they will be assumed to be C# and won't show up unless the C# filter is in effect. You can edit the configuration using the ComponentConfigurations project property. See the help file for details on how the Code Block Component works and what options are available.

Eric