[.NET] XML documentation code tag

[Woy]

Ik ben bezig met een .NET project en ben ook alle code netjes aan het documenteren met XML documentation.

Nu wil ik bij sommige dingen ook wat code Examples toevoegen. dit kan natuurlijk gewoon op de volgende manier.

C#:

/// <example>
/// <code>
/// My Code here
/// </code>
/// </example>

Ik wil echter bij mijn code tag ook aangeven welke language het is, maar ik kan nergens vinden hoe ik dat moet doen. In de MSDN documentatie zie je bijvoorbeeld dat er voor VB.NET/C#/C++/J# code samples gegeven zijn en daar kan je ook op filteren. Dus mijn vraag is, kan je de language ook opgeven in een XML Code Example?

[Woy]

Niemand?

[pedorus]

Als je NDoc of Sandcastle gebruikt, dan is er apart lang attribuut voor, maar het is dus implementatie-afhankelijk. Zie ook deze user's guide to the XML Documentation Comments.

[whoami]

Met Sandcastle lukt het zo:

code:

/// <code language="C#> ... </code>

[pedorus]

whoami schreef op zaterdag 22 november 2008 @ 18:19:
Met Sandcastle lukt het zo:

code:

/// <code language="C#> ... </code>

Ik denk toch dat je

code:

/// <code lang="C#"> ... </code>

bedoeld.

[whoami]

pedorus schreef op zaterdag 22 november 2008 @ 18:32:
[...]

Ik denk toch dat je

code:

/// <code lang="C#"> ... </code>

bedoeld.

Ik was het net even aan het uittesten met Sandcastle voor ik het hier postte (dat builden duurt onwijs lang), en dit:

code:

/// <summary>
/// Class1 blabla
/// </summary>
/// <remarks>wat meer uitleg</remarks>
/// <example>
/// <code language="C#">C# code</code>
/// <code language="VisualBasic">VB.NET code ...</code>
/// </example>
public class Class1
{
}

Resulteert wel degelijk in:

(lang zal een shortcut zijn voor language).

Als ik op 'Visual Basic' klik, dan is enkel de VB.NET code te zien; echter, voor C# heb ik geen zichtbare link ... Dat nog ff uitzoekn.

[ Voor 8% gewijzigd door whoami op 22-11-2008 18:47 ]

[whoami]

Pfft, SandCastle geeft toch echt wel rare output soms.

Met het codevoorbeeld in m'n vorige post krijg ik dus de output die je daar ook ziet staan:
C# code heeft een title, VB.NET code niet.
Voor de VB.NET code is er een link voorzien waarmee je enkel de VB.NET code kunt laten zien, voor de C# code heeft die link geen tekst.

Ik heb dan nog eens een paar andere mogelijkheden geprobeerd, bv:

code:

/// <code lang="cs"> ... </code>
/// <code lang="vb"> ... </code>

In dit geval krijgen de 2 code-voorbeeld secties beiden een titel, maar heb ik de links niet meer waarmee ik de VB code bv onzichtbaar kan maken.

We prutsen nog wat verder ...

[RobIII]

<code lang="cs"> en <code lang="vbnet"> AFAIK (niet getest)

[ Voor 13% gewijzigd door RobIII op 22-11-2008 20:14 ]

[whoami]

RobIII schreef op zaterdag 22 november 2008 @ 20:13:
<code lang="cs"> en <code lang="vbnet"> AFAIK (niet getest)

cs, C#, CSharp
vb, vbnet, Visual Basic

lukken allemaal, maar geven allen eenverschillend resultaat ...

Totnutoe krijg ik (met de Sandcastle Help File Builder) het 'beste' resultaat met:

code:

/// <summary>
    /// Class1 blabla
    /// </summary>
    /// <remarks>wat meer uitleg</remarks>
    /// <example>    
    /// <code language="CSharp" title="C# example" numberLines="true">
    /// C# code
    /// lijn 2
    /// lijn 3
    /// </code>
    /// <code language="VisualBasic" title="VB.NET example">VB.NET code ...</code>
    /// </example>    
    public class Class1
    {
    }

Echter, het is ook nog niet perfect.
Ik krijg nu wel de nodige links te zien, maar deze werken niet 100%

Als ik op 'Visual Basic' klik, krijg ik enkel de VB.NET example code te zien. \o/
Klik ik nadien op 'C#', dan krijg ik zowel de C#, als de VB.NET code te zien.

[ Voor 60% gewijzigd door whoami op 22-11-2008 20:46 ]

[Woy]

Ok thanks, dat was dus het probleem, ik was in de MSDN aan het zoeken, maar het is dus implementatie afhankelijk. Ik gebruikte nu nog NDOC, al heb ik sandcastle ook ginstalleerd staan, maar ik moet nog even uitzoeken hoe dat precies werkt.

[whoami]

Met de Sandcastle HelpFile Builder is het een makkie ...
Je moet gewoon veel geduld hebben

ofwel heb ik een trage bak, dat kan ook ...