Wie zitiere ich "* /" in JavaDocs

Ich muss */ in meinem JavaDoc-Kommentar enthalten. Das Problem ist, dass dies auch die gleiche Sequenz zum Schließen eines Kommentars ist. Was ist der richtige Weg, dies zu zitieren/zu entkommen?Wie zitiere ich "* /" in JavaDocs

Beispiel:

/** 
* Returns true if the specified string contains "*/". 
*/ 
public boolean containsSpecialSequence(String str)

Follow-up: Es scheint, ich / für den Schrägstrich verwenden kann. Der einzige Nachteil ist, dass dies nicht lesbar ist, wenn der Code direkt in einem Texteditor angezeigt wird.

/** 
* Returns true if the specified string contains "*&#47;". 
*/

Quelle

2009-03-10 Steve Kuo

Ich möchte nur hinzufügen, dass dies eines der perfekten Beispiele für eine gute Frage ist. :) – Randolpho

Ich mag den Vorschlag von Bobince, "Sternchen gefolgt von einem Schrägstrich" einzubeziehen, vielleicht in Klammern nach dem Literal "* /". Es ist dann sowohl im Code als auch in Javadoc lesbar. – ide

Verwenden Sie HTML-Escaping.

So in Ihrem Beispiel:

/** 
* Returns true if the specified string contains "*&#47;". 
*/ 
public boolean containsSpecialSequence(String str)

/ entkommt als Zeichen "/".

Javadoc sollte die Escape-Sequenz unbelästigt in den erzeugten HTML-Code einfügen, der in Ihrem Browser als "* /" dargestellt werden sollte.

Wenn Sie sehr vorsichtig sein wollen, könnten Sie beide Charaktere entkommen: */ übersetzt */

Edit:

Follow-up: Es scheint, ich kann & # 47; für den Schrägstrich. Der einzige Nachteil ist , dass dies nicht alles lesbar ist, wenn den Code direkt anzeigen.

Also? Der Punkt ist nicht für Ihren Code lesbar sein, der Punkt ist für Ihren Code Dokumentation lesbar sein. Die meisten Javadoc-Kommentare enthalten komplexes HTML zur Erläuterung. Hell, C# 's Äquivalent bietet eine vollständige XML-Tag-Bibliothek. Ich habe einige ziemlich komplizierte Strukturen darin gesehen, lass mich dir sagen.

Edit 2: Wenn Sie zu viel stört, können Sie eine nicht-javadoc Inline-Kommentar einbetten, die die Kodierung erklärt:

/** 
* Returns true if the specified string contains "*&#47;". 
*/ 
// returns true if the specified string contains "*/" 
public boolean containsSpecialSequence(String str)

Quelle

2009-03-10 19:15:04 Randolpho

hätte ich für die B gehen. –

@Tom Hawtin: Eh, Kartoffeltopf-ah-zu. Entweder funktioniert es. :) – Randolpho

Stört das jemanden außer mir? Nun sieht es im Javadoc gut aus, aber es ist unlesbar, wenn man nur den Quellcode betrachtet ... –

Verwenden Sie die Einheit

*&#47;

In Ihrem Dokumentation wird es als ein "* /" angezeigt

Quelle

2009-03-10 19:15:27 cpatrick

Eine andere Möglichkeit, über die ich stolperte, nur der Vollständigkeit halber: fügen s hinzu ome HTML Markup, das die Ausgabe zwischen * und/nicht verändert.

Verglichen mit der HTML-Escape-Lösung scheint dies ein hässlicher Hack zu sein, liefert aber auch das richtige Ergebnis in der HTML-Ausgabe.

Quelle

2009-03-10 19:39:35 Jonik

Nicht ganz; Ihr Vorschlag, wie er derzeit aussieht, würde wahrscheinlich HTML-Doctypes verletzen. Wenn jemand diese Route gehen würde, würde ich etwas vorschlagen wie: */ um sicherzustellen, dass die Tags geschlossen sind. – Randolpho

Ah, ich habe mich darüber gewundert, aber es so gelassen, weil es die kürzeste Option ist und in IDEA (Ctrl-Q) funktionierte. Wenn nicht , würde nicht * /oder * /suffice? – Jonik

5

Ich würde vorschlagen, dass Sie auch eine Reihe Kommentar hinzufügen irgendwo in der Nähe etwas sagen wie

// */ is html for */

Quelle

2009-03-10 19:44:32 hasen

7

/** * Returns true if the specified string contains "*/". */

Dies ist die ‚richtige‘ Lösung, aber aus Gründen der Lesbarkeit den ich wahrscheinlich gehen würde:

/** * Returns true if the string contains an asterisk followed by slash. */

Quelle

2009-03-10 21:03:15 bobince

7

Niemand erwähnt {@literal}. Dies ist ein weiterer Weg zu gehen:

/** * Returns true if the specified string contains "*{@literal /}". */

Leider kann man nicht */ zu einem Zeitpunkt, entkommen. Bei einigen Nachteilen, korrigiert diese Fehler auch:

Der einzige Nachteil ist, dass dies nicht alles ist, was lesbar ist, wenn Sie den Code direkt in einem Texteditor anzeigen.

Quelle

2014-07-11 10:52:51

Antwort

Verwandte Themen