Eclipse @example Dokumentationsparameter

[mfuesslin]

Hallo,

ich habe folgendes Problem:
Mit dem Parameter @example kann man ja ein Beispiel in den Quellcode tippen. Leider wird dieses bei der Funktions-Vorschau nicht umbrochen.

/**
* Beschreibung blabla
* @param ....
* ...
* @example
* Aufruf: (-> hier soll Eclipse dann umbrechen)
* blabla
* blabla
*/

Wenn ich jetzt mit der Maus über die Funktion fahre, die ich damit beschrieben habe, erhalte ich folgendes Ergebnis:
...
example
Aufruf: blabla blabla

Eclipse umbricht einfach nicht so wie ich im Quelltext umbreche.

Hat jemand ne Idee wo ich da was umstellen kann bzw. obs da nen Trick gibt?

Danke und Grüße
mfuesslin

 

[iLike7Up]

Versuch mal <br>

By the way: Gibts wirklich @example? Nie was davon gehört und in der

http://de.wikipedia.org/wiki/Javadoc#.C3.9Cbersicht_der_Javadoc-Tags

stehts auch nicht =)

Edit: Man kann sich natürlich seine eigenen Tags bauen =)

 

[DjNDB]

Seit JDK 1.5 gibt es ein {@code} Tag.

Das kannst du z.B. so verwenden:

/**
 * <pre>
 * {@code 
 * System.out.println( line );
 * raf.writeBytes( OK_STRING );
 * } 
 * <pre>
 */

Man kann auch die führenden Sterne weglassen, sodass man direkt code reinkopieren kann:

/**
 * <pre>
{@code
while ( true )
{
    while ( true )
    {
    }
}
}
 * <pre>
 */

Dann muss man aber mit dem Code Formatter aufpassen. Dort kann man jedoch abschalten, dass er in Kommentaren Code in <pre> tags formatiert.
Wenn einem die Tabs im Browser zu groß sind, kann man Tabs durch Leerzeichen ersetzen um die Größe festzulegen.

 

[roker002]

Du kannst alle HTML Tags benutzen!

 

[mfuesslin]

Danke für die Tipps, wusste nicht, dass ich da HTML verwenden kann.
Den @example Tag gibts wirklich:
Die Code-Complete Funktion bietet mir wenn ich in einer Funktionsbeschreibung "@" drücke unteranderem "@example" an...

Verwende die EE Version + PHP SDK

Gruß

 

[DjNDB]

Aahh, sag doch gleich, dass es um PHP geht.

Eclipse verwendet soweit ich das sehe PHPDoc.

Hier ist die Dokumentation vom @example Tag.

Es ist offenbar überhaupt nicht so gedacht wie du es vorhast. Damit kann man Codezeilen aus Dateien in den Kommentar einbinden.
Wenn du direkt Code angeben möchtest kannst du das HTML Tag <code></code> verwenden.

Das ist übrigens wieder ein gutes Beispiel, dass man immer zuerst Dokumentation lesen sollte, anstatt einfach etwas zu verwenden das autocomplete anbietet und zu vermuten wie es funktionieren könnte.

 

[mfuesslin]

Danke für die Hilfe.
Aber was spricht dagegen, einfach @example so zu verwenden, wie ich es tue:

@example
<code>
...
</code>

Das sieht dann in meinen Augen ganz wunderbar aus:
...
example
Hier steht dann der Code.

ist ja im Grunde genau so wie die das einsetzen, nur dass ich nicht auf eine externe Beispieldatei verlinke, sondern das Beispiel direkt integriere. Vom Sinn her im Prinzip genau gleich.

Gruß

 

[DjNDB]

Aber was spricht dagegen, einfach @example so zu verwenden, wie ich es tue:

@example
<code>
...
</code>

Das sieht dann in meinen Augen ganz wunderbar aus:
...
example
Hier steht dann der Code.

Ich weiß jetzt nicht wie streng der Parser ist, aber in meinen Augen ist es unsinnig ihm mit @example zu sagen, dass er eine Datei einbinden soll, aber keine anzugeben, nur damit man example fett gedruckt geschrieben bekommt.
Gibt der Parser da keine Warnung aus?

Sauberer wäre stattdessen <b>example</b> zu verwenden um Fetten Text auszugeben. Das Ergebnis könnte im HTML das gleiche sein (ich hab das nicht ausprobiert, nur aus der Doku gelesen), aber wer den Code später mal liest wird sich so nicht wundern was das soll.