Fett oder kursiv in C# oder VB Dokumentation Kommentare?

Question

Gibt es eine Möglichkeit fett oder italic in Dokumentationskommentare zu verwenden? Etwas wie:

/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary> 
public void CleanAll(); 

List of predefined tags enthält keine so Funktionen, aber wissen Sie, irgendeine Art und Weise Nachdruck zu erreichen/Hervorhebung? Vorzugsweise, wenn es auch in Tooltips angezeigt werden könnte, wenn Sie den Mauszeiger über den Code bewegen.

Wir haben <c> und <code> dort, aber sie haben bereits ihre Semantik.

Answer 1

Nicht streng, nein. Allerdings Sandcastle (ein Dokumentationsgenerator, der HTML aus der Dokumentation generiert) unterstützt nur HTML dort zu verwenden, so können Sie <em> und <strong> einfach gut verwenden, wenn Sie es mit Sandcastle erstellen.

Um es anders auszudrücken: Wie Jamiec bereits bemerkt, sind XML-Dokumentation Kommentare nur XML. Sie können also alle gültigen XML-Dateien einfügen. Der Compiler wird das gerne in die XML-Dokumentationsdatei schreiben. Alles hängt von der Software ab, die diese Datei verarbeitet. Sandcastle übergibt alles, was es nicht kennt, als HTML, da es sowieso das Ausgabeformat ist.

Visual Studio wird sie einfach ignorieren, wenn die Hilfe Tooltip Anzeige:

ReSharper in seiner Ctrl + Q Ansicht werden HTML-Tags zeigen als Text, die Dinge ein bisschen hässlich macht:

Die sind normalerweise nur von Interesse, wenn yo Sie können jedoch eine Bibliothek erstellen, die von anderen verwendet wird. Aber es bedeutet auch, dass innerhalb der IDE niemand Ihre Betonung wie beabsichtigt sehen kann.

Ich habe tatsächlich wenig Nachdruck beim Schreiben von API-Dokumentation gefunden; oft können Sie einen Satz anders schreiben oder restrukturieren, um wichtige Knoten in einem separaten Absatz am Ende zu haben, um überhaupt keine Betonung zu benötigen. Konsequente Sprache und Phrasierung hilft dem Leser auch, wichtige Notizen aufzunehmen, wenn er einmal damit vertraut ist.

Ihr Code war wahrscheinlich nur ein Beispiel, aber ich denke, die Zusammenfassung braucht am wenigsten betont, da es nur in einem kurzen Satz - was ein Typ ist oder eine Methode tut. Wenn überhaupt, verwende es in den Bemerkungen und selbst dann würde ich sorgfältig überlegen, ob du es wirklich brauchst.

Answer 2

Eine andere Möglichkeit besteht darin, stattdessen einen Wiki-Markup-ähnlichen Stil zu verwenden.

/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary> 
public void CleanAll();