Wieso ist Javadoc mit Html Tags?

[DEvent]

Hallo,

bin ich der einzige Programmierer, dem es nicht gefällt, dass man für Javadoc Html Tags braucht?

Gut, der Vorteil ist, man kann sehr ausführlich seine Javadoc designen, mit Tabellen, Bildern, usw. Aber ein gravierender Nachteil ist wohl, dass man ein extra Programm braucht um das geschriebene Javadoc lesen zu können. Bei fast allen Javadocs im JDK sind überall die Html-Tags, so dass man nur sehr schwer was lesen kann.

Z.B:

embedded in the message pattern is specified (<b>()?</b> signifies optionality):<br /><code>{</code><i>argument-number</i><b>(</b><code>,</code><i>format-name</i><b>(</b><code>,</code><i>format-style</i><b>)?)?</b><code>}</code>

Wieso wurde nicht eine leichte Formatierung gewählt, wie z.B. in Org-Mode von Emacs? Im Org-Mode kann ich Text, Tabellen und Listen formatieren, aber der Text bleibt dabei vollständig lesbar.

Da man mit dem jetzigem System eh ein Anzeige-Programm braucht (z.B. einen Web-Browser), hätte man Links, Tabellen und Hervorhebungen doch dem Anzeige-Programm überlassen können. Anstelle das man schreiben muss

<ul><li>Eins</li><li>Zwei</li><li>Drei</li></ul>

, hätte man das auch so lösen können:

* Eins
* Zwei
* Drei

Dazu kommt noch, dass Html schreiben eine Qual ist. Somit brauche ich ein extra Programm um a) Javadoc zu schreiben und b) Javadoc zu lesen.

Ich kann mir einfach nicht vorstellen, dass sich keine Programmierer die Frage stellen wieso wir Html Tags für Javadoc verwenden.

Kann man irgendwas anderes verwenden und wird es verwendet, oder sind alle mit den Html-Tags und dem Zwang einen Html-Editor und Html-Anzeige benutzen zu müssen zufrieden?

 

[Gassst]

Thema ist jawohl irrelevant, da sowas jede IDE kann !?

 

[triopsfreak]

Also ich finde das praktisch, schliesslich hat wohl jeder, der einen Grund hat javadocs zu lesen, auch einen Browser, oder?
Und das meiste HTML wird soweit ich weiss, sowieso von javadoc selber generiert, damit halt alles so aussieht wie die Java-Api auch!

 

[Tomate_Salat]

Ich kann deine Argumentation beim besten willen nicht nachvollziehen. Wenn du eine gescheite IDE hast, dann wird dir auch alles korrekt angezeigt. Die Tools um eine Javadoc zu generieren oder auszulesen sind auch darin vorhanden.

Wenn du deine Doku auf deine Homepage stellen willst, dann hast du es schon im passenden Format.

Also, alles in allem eine gute Sache.

 

[DEvent]

Also ich lese extrem selten das erzeugte Html. Die meiste Zeit klicke ich (in Eclipse) mit Strg+Maus auf den Typen/Methode und dann komme ich direkt in den Quellcode rein. Dann lese ich das Javadoc (was hoffentlich nicht durch Html-Tags unlesbar gemacht worden ist) und den Quellcode der Methode/Klasse.

Dann komme ich in die Situation wo das Javadoc vollkommen unlesbar ist und dann muss ich umständlich den Browser hervor kramen. In den Browser muss ich erst die Seite finden, dann den Typen und Methode suchen.

Meistens reicht es auch den Mauszeiger über den Typen/Methode zu bewegen und es erscheint ein Fenster mit dem Javadoc. Aber das ist ziemlich klein, so dass es nur für ein kurzes einlesen reicht. Um den gesamten Text zu lesen muss ich wieder den Browser hervor kramen.

Und wie schreibt ihr Javadoc? Da braucht man wieder einen Html Editor, vielleicht noch einen WYSIWYG Editor. Ich bin hier um Code zu schreiben, nicht eine Webseite zu designen.

@Gassst: Was kann den die IDE? Bei Eclipse ist Html ganz arm, da brauche ich wieder Plugins. Und wenn ich den Quellcode offen habe, dann sehe ich nur Html-Tags. Und wenn ich Javadoc schreiben will, dann wieder entweder Plugins oder per Hand und beides ist furchtbar.

 

[bygones]

Kann man irgendwas anderes verwenden und wird es verwendet, oder sind alle mit den Html-Tags und dem Zwang einen Html-Editor und Html-Anzeige benutzen zu müssen zufrieden?

Du kannst deine Javadoc auch anders schreiben, nur werden dann andere ein Problem bekommen.

Und da man so und so in IDEs arbeitet ist dein argument nichtig

 

[faetzminator]

bin ich der einzige Programmierer, dem es nicht gefällt, dass man für Javadoc Html Tags braucht?

Warscheinlich schon denn Javadoc ist dazu da, mit dem Generator zu einer Page generiert zu werden. Wie auch z.B. auch die API unter Java Platform SE 6

Aber ein gravierender Nachteil ist wohl, dass man ein extra Programm braucht um das geschriebene Javadoc lesen zu können.

Ein Browser!? Und die IDEs können HTML meist auch anzeigen.

Bei fast allen Javadocs im JDK sind überall die Html-Tags, so dass man nur sehr schwer was lesen kann.

Du musst die Javadoc auch nicht im Source lesen...

Wieso wurde nicht eine leichte Formatierung gewählt, wie z.B. in Org-Mode von Emacs? Im Org-Mode kann ich Text, Tabellen und Listen formatieren, aber der Text bleibt dabei vollständig lesbar.

Dann müsste das also beim generieren zuerst in HTML umgewandelt werden ???:L ?

Dazu kommt noch, dass Html schreiben eine Qual ist. Somit brauche ich ein extra Programm um a) Javadoc zu schreiben [...]

Normalerweise benötigt man nicht viel HTML!? Aber wenn dir das Schwierigkeiten macht, kannst du natürlich Frontpage o.ä. (Frontpage ist wohl das Tool, welches die meisten User eh schon mit M$ Office drauf haben) verwenden.

Ich kann mir einfach nicht vorstellen, dass sich keine Programmierer die Frage stellen wieso wir Html Tags für Javadoc verwenden.

Wurde bereits implizit beantwortet.

Kann man irgendwas anderes verwenden und wird es verwendet, oder sind alle mit den Html-Tags und dem Zwang einen Html-Editor und Html-Anzeige benutzen zu müssen zufrieden?

Meine Wenigkeit hat kein Problem mit HTML.

Schlussfolgerung: Du hast was gegen HTML !?

 

[triopsfreak]

Du sagst ja, du musst keine Website designen, brauchst du auch nicht! Und bei Eclipse kannst du auch ganz einfach länger über dem Gelben Fenster bleiben, dann erscheint ein Rand mit dem du das Fenster grösser ziehen kannst! Und ein bisschen Kenntnis in HTML kann auch nicht schaden!

 

[DEvent]

Warscheinlich schon denn Javadoc ist dazu da, mit dem Generator zu einer Page generiert zu werden. Wie auch z.B. auch die API unter Java Platform SE 6

Ein Browser!? Und die IDEs können HTML meist auch anzeigen. Du musst die Javadoc auch nicht im Source lesen...

Javadoc ist aber im Quellcode. Wenn ich schon den Quellcode offen habe, wieso sollte ich noch extra einen Browser nur für das Javadoc offen haben? Wenn ich den Quellcode offen habe, will ich alles lesen können, normalerweise brauche ich dafür auch kein Anzeigeprogramm, bloß einen Texteditor.

Dann müsste das also beim generieren zuerst in HTML umgewandelt werden ???:L ?

Es ist mir doch egal, ob es erst in Html umgewandelt wird. Mir geht es darum, dass ich den Quellcode ohne ein extra Anzeigeprogramm lesen kann. Aber da Javadoc voll mit Html-Tags ist, geht das leider nicht.

Wieso verwenden wir hier im Forum BB-Tags und keine Html-Tags? U.a. weil sie wesentlich leichter zu tippen sind. Die Forumsoftware macht sie dann in Html-Tags um, die dann der Browser anzeigen kann.

Das gleiche hätte ich gerne für Javadoc. Z.B. in Doxygen, was keine Html-Tags benötigt und trotzdem gerne Html generiert.

Was ist einfacher zu lesen und zu schreiben a) oder b)?

a)

<ul>
<li>Eins,</li>
<li>Zwei,</li>
<li>Drei,</li>
<ul>

b)

* Eins,
* Zwei,
* Drei

Wohl doch b) oder? Das javadoc Programm kann aber aus b) genauso leicht Html erzeugen und eine Seite anzeigen, wie es aus a) machen kann.

Doxygen
In Doxygen kann man auch Listen erstellen, man müllt aber einen nicht mit Html-Tags zu, so dass man mit einem Texteditor zurecht kommt.

Normalerweise benötigt man nicht viel HTML!? Aber wenn dir das Schwierigkeiten macht, kannst du natürlich Frontpage o.ä. (Frontpage ist wohl das Tool, welches die meisten User eh schon mit M$ Office drauf haben) verwenden.

Nur für eine simple Liste brauche ich 4 Html Tags. Für eine Tabelle kommen 8 Tags hinzu. Für eine Hervorhebung brauche ich 2 Html Tags.

Wurde bereits implizit beantwortet.

Meine Wenigkeit hat kein Problem mit HTML.

Schlussfolgerung: Du hast was gegen HTML !?

Ja, ich habe was gegen Html, wenn ich es lesen und schreiben muss und wenn ich Frontpage brauche um meinen Java Code zu schreiben.

 

[DEvent]

Du sagst ja, du musst keine Website designen, brauchst du auch nicht! Und bei Eclipse kannst du auch ganz einfach länger über dem Gelben Fenster bleiben, dann erscheint ein Rand mit dem du das Fenster grösser ziehen kannst! Und ein bisschen Kenntnis in HTML kann auch nicht schaden!

Mein Eclipse zeigt z.Z. gar kein HTML mehr an. Siehe mein anderen Thread dazu. Somit nervt mich Javadoc gerade etwas mehr als sonst.

 

[Gast2]

Du sagst du benutzt Eclipse??? Anscheinend nicht richtig...

 

[triopsfreak]

Du musst es ja nicht schreiben, es sieht auch ohne HTML Tags gut aus, und ich finde es wesentlich einfacher, wenn ich im Browser einfach die API offen habe, dann sieht man auch nur den Namen und die Beschreibung der Methode und nicht den ganzen Rumpf.

 

[mvitz]

Eigentlich ist schon alles gesagt, aber unter Eclipse kannst du z.B. die Javadoc View nutzen, wenn dir das hilft (siehe Screenshot) ansonsten, für das eigene schreiben braucht man ja nur Tabellen, Listen und evtl. noch Fett/Kursiv und das wenige HTML sollte man gerade noch zusammen bekommen.

 

[faetzminator]

Javadoc ist aber im Quellcode. Wenn ich schon den Quellcode offen habe, wieso sollte ich noch extra einen Browser nur für das Javadoc offen haben?

Meistens les ich die Javadoc Comments nur von Libs, welche ich einbinde. Und die komplextesten Javadoc-Kommentare sind sowieso meisten jene, welche dir erklären, was die Klasse tut - und das solltest du als Verwender dessen bereits wissen.

Wieso verwenden wir hier im Forum BB-Tags und keine Html-Tags? U.a. weil sie wesentlich leichter zu tippen sind.

Drei Gründe:
1. Nicht alle HTML-Tags sind erlaubt. So kann man einfach den ganzen Input escapen, bevor man die BB-Tags auflöst (bzw. wird der Post auch mit BB-Tags in der DB gespeichert).
2. Das Forum kann die Eingaben ganz an seine Wünsche anpassen. Vielleicht hat man auch später ein GWT Frontend, welche die BB-Tags genau so parsen (und statt HTML irgendwelche Java-Objekte erzeugt) kann. Ohne Probleme mit HTML.
3. Die BB-Tags entsprechen nicht zwingend einem HTML-Tag. So könnte man z.B. [c][slideshow][*]1.png[*]2.png[/slideshow][/c] implementieren.
Bis auf Punkt 3 (wär vielleicht eine Idee) gilt das aber für Javadoc sowieso nicht.

Was ist einfacher zu lesen und zu schreiben a) oder b)?

Da hast du natürlich recht, aber es ist IMHO einfach praktikabler, das gleich von Anfang an mit HTML zu erstellen. Wie du weisst, ist HTML eigentlich nicht fürs "plain lesen" gedacht.

Nur für eine simple Liste brauche ich 4 Html Tags.

Naja, kennen musst du aber nur zwei

Ja, ich habe was gegen Html, wenn ich es lesen und schreiben muss und wenn ich Frontpage brauche um meinen Java Code zu schreiben.

Learning by doing

 

[TheDarkRose]

Ja, ich habe was gegen Html, wenn ich es lesen und schreiben muss und wenn ich Frontpage brauche um meinen Java Code zu schreiben.

Du denkst wohl zu kompliziert? Wieso solltest du Frontpage brauchen um dein Javadoc zu schreiben??? *wirrsinn*

 

[Gassst]

@Gassst: Was kann den die IDE?

Hä, JavaDoc anzeigen und JavaDoc schreiben kann ich mit meiner. Methode anklicken und strg+Q dann wird mir die formatierte Dokumentation angezeigt. und HTML kann ich natürlich auch editieren im Kommentar (aber schließende HTML Tags einfügen kann auch eigentlich jeder texteditor...). Ich benutz zwar IntelliJ aber soweit ich weiß kann Eclipse das ebenso (siehe posts über mir)

 

[DEvent]

Da hast du natürlich recht, aber es ist IMHO einfach praktikabler, das gleich von Anfang an mit HTML zu erstellen. Wie du weisst, ist HTML eigentlich nicht fürs "plain lesen" gedacht.

Naja, kennen musst du aber nur zwei

Learning by doing

Praktikabel für wen oder was? Praktikabel für das Javadoc Programm? Dem Javadoc Programm kann es egal sein ob du eine Liste als

<ul><li></li></ul>

oder als * Eins, * Zwei, * Drei schreibst. Das Javadoc Programm kann aus beidem eine Seite generieren.

Für einen Menschen sind Html-Tags sicher nicht praktikabel, nicht fürs lesen und nicht fürs schreiben.

Quellcode liest du aber schon "plain"? Wieso kann man dann nicht ein Javadoc Format nehmen, dass man auch "plain" lesen kann?

 

[TheDarkRose]

Weil Javadoc dazu gedacht ist, die Dokumentation im generierten HTML zu lesen und nicht im Quellcode herumzuwurschteln. IMHO hat man im Quellcode von fremden Libraries und API's so und so nichts verloren, außer man entwickelt daran mit.

 

[tfa]

Für einen Menschen sind Html-Tags sicher nicht praktikabel, nicht fürs lesen und nicht fürs schreiben.

Das ist leider so. Man kann's nicht ändern. Redest du hier über Quelltext für Bibliotheken oder Endanwendungen? Bei Libs wird man nicht darum herum kommen, seine Java-Docs mit HTML aufzuhübschen. Bei normalen Anwendungen erzeugt man die normalerweise sowieso nicht. Dann kann man sich auch HTML-Tags schenken.

 

[DEvent]

Weil Javadoc dazu gedacht ist, die Dokumentation im generierten HTML zu lesen und nicht im Quellcode herumzuwurschteln. IMHO hat man im Quellcode von fremden Libraries und API's so und so nichts verloren, außer man entwickelt daran mit.

Also dieser Meinung kann ich mich überhaupt nicht anschließen. Ich weigere mich eine Bibliothek zu benutzen, dessen Quellcode ich nicht habe, ganz einfach aus dem Grund, dass man aus dem Javadoc nicht immer ermitteln kann, was der Code macht.

Eine Javadoc kann veraltet sein, oder der Entwickler war einfach zu faul oder hat etwas vergessen. Der Code ist immer akkurat und aktuell.

Deswegen lese ich immer den Code zu dem Javadoc, wenn mir etwas unklar ist. Da ist es praktisch, wenn ich den Javadoc lesen kann ohne einen Web-Browser.

 

[faetzminator]

Also dieser Meinung kann ich mich überhaupt nicht anschließen. Ich weigere mich eine Bibliothek zu benutzen, dessen Quellcode ich nicht habe, ganz einfach aus dem Grund, dass man aus dem Javadoc nicht immer ermitteln kann, was der Code macht.

Das schliesst sich aber gegenseitig nicht aus. Wenn ich die Lib einbinde, dann les ich mir online Beispiele und die Javadoc. Wenn ich mir danach den Source anschauen will, dann kann ich das ebenfalls. Wenn mich dann die HTML-Tags in der Javadoc stören, dann stell ich am Besten den Computer aus

 

[Tomate_Salat]

Quellcode liest du aber schon "plain"? Wieso kann man dann nicht ein Javadoc Format nehmen, dass man auch "plain" lesen kann?

Weil HTML ein gängiges weit verbreitetes Format ist, dass (denke ich) jeder Entwickler kennt und in einem gewissen Umfang einsetzen kann. Und wie bereits gesagt: die IDEs von heute bieten dir genug Möglichkeiten, die Dokumentation zu lesen. Wenn du der doku nicht vertraust und extra den Source zu rate ziehst, verstehe ich auch nicht, wo das Problem wäre, notfalls die Onlinedokumentation (oder ggf die heruntergeladene Version) in einem browser zu öffnen (was btw auch in einer IDE möglich ist)

 

[ARadauer]

Ich bin DEvents Meinung... ich lese und schreibe javadoc nur im Code. Ich finde es lästig wenn manche Entwickler sehr aufwändigen HTML code in den Kommentaren drinnen haben...

 

[BlackViruZ]

Also dieser Meinung kann ich mich überhaupt nicht anschließen. Ich weigere mich eine Bibliothek zu benutzen, dessen Quellcode ich nicht habe, ganz einfach aus dem Grund, dass man aus dem Javadoc nicht immer ermitteln kann, was der Code macht.

Ich verstehe dein Problem nicht - wirklich nicht. Jedes halbwegs nutzbare IDE bietet es einem an die Javadoc dir gerendert anzeigen zu lassen.
Den Sourcecode kann man doch immernoch zur Rate ziehen wo ist da die Kollision?!
Ich meine.. wenn du unbedingt darauf bestehst dir die Javadoc ausschließlich im source anzugucken, du aber kein HTML kannst... dann lerne es vllt?

Man kann auch sagen "ja hmm ich will aber nichts neues lernen, keine tools einsetzen, keinen Aufwand haben, aber ich habe genug Zeit im Forum über javadoc zu meckern.."
In der Zeit wo du hier dieses Hin und Her, wo du jegliche Antworten als "ich mach das aber so und so" abgestempelt hast, hättest du längst die für Javadocs wirklich nötigen tags lernen können UND dich daran gewöhnen können HTML zu lesen.
Ist ja nicht so als würde im allgemeinen da nen javascript basiertes Bildbearbeitungsprogramm in der Javadoc stehen...

Eine Javadoc kann veraltet sein, oder der Entwickler war einfach zu faul oder hat etwas vergessen. Der Code ist immer akkurat und aktuell.

Und wie genau löst dein vorschlag mit, einfach irgendwelche zeichen als Strukturelemente zu bezeichnen (was ja btw HTML auch macht... nur halt mit Tags..) an dem Problem?
Wird die Javadoc dadurch aktueller?

Deswegen lese ich immer den Code zu dem Javadoc, wenn mir etwas unklar ist. Da ist es praktisch, wenn ich den Javadoc lesen kann ohne einen Web-Browser.

Man kann sich z.B. bei Eclipse, wie schon erwähnt, die gerenderte Form angucken.
Auch wenn du "nur" den source hast.

 

[schalentier]

Also manchmal bin ich echt erstaunt ueber die Engstirnigkeit einiger Forenteilnehmer hier. Mir ist voellig unverstaendlich, wie man HTML Tags schoener und angenehmer finden kann, als eine beliebige, leicht zu lernende und fuer jeden verstaendliche Wikistyle-Syntax (oder BBCode, oder sonstwas).

Da JavaDoc allerdings schon ein paar Jahre auf dem Buckel hat - und zu einer Zeit entstanden ist, als es noch keine Wikipedia gab (oder?) - wurde damals HTML gewaehlt. Sowas im Nachhinein zu aendern ist immer schwierig.

Besonders lustig wird btw, wenn man deutsche Kommentare schreibt und Umlaute dann korrekt mit ü & co schreibt.

Gibts eigentlich ne Alternative zu JavaDoc? Eine wo kein HTML geschrieben werden muss?

 

[TheDarkRose]

Ja HTML Tags sind nicht schön zum lesen, aber wie schon vorher erwähnt wurde, warum nicht parallel die von der IDE gerenderte Version lesen? Wo ist das Problem?

 

[Beni]

Du kannst dir von JavaDoc die Kommentare suchen lassen, und sie dann selbst verarbeiten. Wenn ich mich recht erinnere, ist das die Doclet API. Dann kannst du nach belieben irgendwelche Wiki-Tags in Html-Tags übersetzen. Ob das schonmal jemand gemacht hat, kann ich dir nicht sagen.

Vor ein paar Jahren habe ich mal zum Spass diese API benutzt um mein eigenes JavaDoc-View zu basteln. Es war wirklich kein grosser Aufwand.

 

[Tomate_Salat]

Habt ihr alle eine IDE weil ihr den Splashscreen so schön findet :joke:?

Ich kann mir nicht vorstellen, dass wer für jede Methode, über die er eine kurze Info zu rate ziehen möchte, sich den Source anschaut.

Eclipse hält sogar einen direktlink(shift+f2) zur Api im Browser bereit(!), wo man sie sich formatiert in der IDE anschauen kann. Im Notfall kann man sich den Javadoc-view einstellen. Den kann man so groß ziehen wie man möchte. Wenn man genug Bildschirme hat, kann man diesen View sogar auf einem eigenen Monitor platzieren und der zeigt auch immer die interessante Stelle an.

 

[Gast2]

Habt ihr alle eine IDE weil ihr den Splashscreen so schön findet :joke:?

Hat Notepad ein Splashscreen ??? :joke:

 

[Tomate_Salat]

Notepad ist in meinen Augen keine IDE :joke: (genauso wie Visual Studios in meinen Augen keine IDE ist, sondern einfach nur eine Katastrophe :shock

 

[bygones]

du sollst nicht den code einer bib lesen sondern deren Api nutzen - das ist schonmal ein fehler. Wie etwas implementiert wird von einer lib kann dir voellig egal sein (und soll es dir auch). Was dich angeht ist nur die API wichtig. Wenn diese schlecht gepflegt ist in jeglicher Form ist das ein weitaus anderes und schwerwiegerendes Problem als ob die Javadoc nun in HTML ist oder nicht.
APIs sind nicht da um den Code zu lesen, weder den Javacode, noch den HTML-Javadoc code

 

[Cody]

@DEvent: Ändere doch einfach das Javadoc-Syntaxhighlighting und passe die Tag-färbung mehr dem Hintergrund an...diese Möglichkeit bietet Eclipse. Wenn man halt solche Probleme hat und Eclipse da Abhilfe schaffen kann, wenn man es schon benutzt, dann sollte man das auch nutzen!

Ich glaube aber es geht hier weniger um das "Abhilfe" schaffen sondern mehr darum Alternativen zu finden...oder?
Aber welche Alternativen gibt es da schon für das Markup um Javadoc generieren zu lassen welches man extern OHNE Source und ohne doppelte Arbeit, lesen kann ?

Mal das "Oracle" befragen ob sich so eine Gravierende Änderung an Java überhaupt lohnt und vor allem Sinn macht.

 

[darekkay]

Mal davon ganz abgesehen, dass man die HTML-Grundlagen als Programmierer einfach kennen sollte - dir gefällt es einfach nicht, okay. Aber gerade Eclipse bietet dir doch die Möglichkeit, diesen "unlesbaren" Code formatiert anzuzeigen. Dies wurde hier schon mehrmals erwähnt und auch ein Screenshot gepostet. Alleine mit der Maus über die jeweilige Klasse/Methode zu gehen, öffnet bereits die formatierte Ausgabe. Und da kommt selbst dein

* 1
* 2
* 3

Format nicht ran, da eine formatierte Ausgabe noch einen Tick lesbarer ist(logisch). Warum du darauf überhaupt nicht eingehst und dir nur die "besten" Zitate raussuchst ("ich will mein javadoc nicht in frontpage schreiben", wtf?), deutet darauf hin, dass du anscheinend eher nach einen kontroversen Gespräch suchst, als dein Problem lösen willst.

 

[mvitz]

Zu ergänzen ist übrigens noch, dass Javadoc afaik sehr gnädig das HTML interpretiert.
Für eine Liste geht z.B.:

/**
 * This is a test with a list
 * <ul>
 * <li>One
 * <li>Two
 * <li>Three
 * </ul>
 * and more text.
 */
public final class JavadocTest {}

Und das ist jetzt auch nicht mehr so viel unleserlich als

This is a test with a list
* One
* Two
* Three
and more text.

 

[tfa]

Zu ergänzen ist übrigens noch, dass Javadoc afaik sehr gnädig das HTML interpretiert.

Javadoc interpretiert gar kein HTML, das macht dein Browser.

 

[ARadauer]

Ich bin überascht über die Aggresivität die einem hier entgegenschlägt wenn man anderer Meinung ist.

Privat mache ich seit ca 15 Jahren Webdesign, also ich kann HTML. Und klar zeigt mir die IDE den formatierten Code in einer anderen View an. Ich finde es allerdings unangenehm wenn ich mich durch fremden Code bewege auf Kommentar zu stoßen der durch Struktur Elemente unterbrochen ist.
Das ist ein Fakt: "Ich finde es unangenehm Prosatext zu lesen der durch Struktur Elemente wie HTML Tags unterbrochen ist"

 

[mvitz]

@tfa: stimmt natürlich, ich wollte damit eher ausdrücken, dass Javadoc nicht zwangsweise wohlgeformt sein muss

@aradauer: auch da gebe ich dir Recht, allerdings finde ich die Strukturelemente diverser Wiki-Sytaxen auch nicht besser zum direkten lesen und da kommt nun mal dazu, dass es diese afaik zur Einführung von Javadoc noch nicht gab und es heute Aufgrund der Anzahl Schwierigkeiten gäbe sich auf eine zu einigen. Ganz auf Strukturelemente zu verzichten halte ich dann allerdings auch für falsch, denn Javadoc ist nun mal nicht primär dafür gedacht, die Kommentare im Source Code zu lesen, sondern sich aus den Sourcen eine API Dokumentation zu generieren.

 

[Gast2]

Das ist ein Fakt: "Ich finde es unangenehm Prosatext zu lesen der durch Struktur Elemente wie HTML Tags unterbrochen ist"

Geht mir auch so. Verwende die HTML Tags sehr sparsam. Ich denke aber auch es ist einfach historisch so gewachsen. Aufregen hilft nicht.

Und falls mans gar nicht mag gibts ja noch doxygen. Das wird halt dann nicht in der IDE integriert.

 

[Tomate_Salat]

@ARadauer: Was hindert dich daran, die IDE-Hilfestellungen auch im Source zu nutzen? Der hover-effekt und das andere Zeugs funktioniert dort ebenso.

 

[tfa]

@ARadauer: Was hindert dich daran, die IDE-Hilfestellungen auch im Source zu nutzen? Der hover-effekt und das andere Zeugs funktioniert dort ebenso.

Weil das total unpraktisch ist? Wenn der Text eh im Editor ist, wieso soll ich ihn nicht gleich dort lesen? Erst die Maus in die Hand zu nehmen, den Zeiger auf die richtige Stelle schieben und 1/2 Sekunde warten, bis der Tooltip erscheint, würde mich echt stören. Besonders, weil ich lieber mit der Tastatur arbeite.

Wie gesagt, für allgemeine APIs, Libs und Bibliotheken muss man mit HTML in den Kommentaren leben. Aber in Code, den man nur selbst in der IDE liest, haben HTML-Tags nichts zu suchen.

 

[stulleman]

Quellcode liest du aber schon "plain"? Wieso kann man dann nicht ein Javadoc Format nehmen, dass man auch "plain" lesen kann?

Warum sollte man es dann noch formatieren?
Und überhaupt verstehe ich dein Problem nicht, die JavaDoc statt mit dem Editor, einfach mit dem Browser auf zumachen?

 

[Cody]

Das DEvent dieses Thema angesprochen hat, rührt wohl ehr daher: Kein Html mehr in Javadoc Hilfe und der daraus entstandene Umstand gebündelt mit Frust

Aber alles nur reine Spekulation und Vermutung :bae:

 

[Tomate_Salat]

@tfa: Der hover-effekt ist nicht die einzige Möglichkeit. Andere wurden bereits genannt, welche ohne eine Maus auskommen.

 

[tfa]

@tfa: Der hover-effekt ist nicht die einzige Möglichkeit. Andere wurden bereits genannt, welche ohne eine Maus auskommen.

In der Tat. Es gibt noch umständlichere Methoden.

 

[Sonecc]

Also ich finde, denn Kaffee muss man gegen den Uhrzeigersinn umrühren.
Wer das mit dem Uhrzeigersinn macht ist ja sowieso doof.


Und ich dachte dass das Durchschnittsalter > 12 liegt.
Scheinbar ist das nicht so, sonst gäbe es diese "mein Förmchen ist schöner"-Diskussion nicht.


Ums mal ganz konkret zu sagen: JavaDoc kann durch HTML-Tags formatiert werden und ist dazu gedacht das Erstellen und Pflegen einer Doku zu vereinfachen.
Wer also will, dass der Kommentar zu einer Methode auch von anderen gelesen werden soll, sollte JavaDoc verwenden (und damit eben auch HTML). Alle anderen brauchen keinen JavaDoc Kommentar machen und können einfach einen unformatierten mehrzeiligen Kommentar verwenden.

Auf diese Beurteilung scheint hier keiner zu kommen, stattdessen meinen die einen alles muss mit HTML gemacht werden (so kommts teils rüber) und die anderen sind der Meinung alles muss ohne.
Auf die Idee zu kommen, dass es auch möglich ist eine Methode zu kommentieren ohne JavaDoc ist hier wohl bisher keiner....

Stattdessen giftet man sich auf Kindergartenniveau an

 

[tfa]

Auf die Idee zu kommen, dass es auch möglich ist eine Methode zu kommentieren ohne JavaDoc ist hier wohl bisher keiner....

Wir war so, als hätte ich das vorgestern in #19 schon geschrieben.

 

[Tomate_Salat]

@Sonecc: Ich denke, das dürfte jedem klar sein. Wer kein HTML in JavaDoc mag, wird es sicher nicht verwenden. Es geht viel mehr darum, dass es verwendet wird.

@tfa: Dann hast du nicht wirklich die Vorschläge gelesen. Schau dir mal auf Seite 1 den Screenshot von Mvitz an und erkläre mir mal bitte, was daran umständlicher ist.

Ich verstehe diese Abneigung gegen dieses JavaDoc-View einfach nicht. Abgesehen von der HTML-Darstellung bietet es noch die Verlinkung auf eine andere Klasse, Methode,... Das bringt doch nur Vorteile und das einzige was man machen braucht, ist die Augen zu bewegen.

 

[darekkay]

Um es mal zusammenzufassen:

a) Wer SELBST ein Programm schreibt, macht einfach was er will (HTML-Hasser lassen's weg, Durchschnittsuser nehmen etwas davon mit rein, HTML-Liebhaber müllen es mit allen Möglichkeiten, die HTML bietet, zu) -> es ist also jedem selbst überlassen

b) Wer FREMDE Programme liest, muss sich damit abfinden, dass es die 3 in a) erwähnten Menschentypen gibt. Entweder man nimmt die "Unannehmlichkeiten", wie 0.5sek auf den Tooltip warten, in Kauf, oder man verzichtet einfach auf alle Klassen/Bibliotheken, die HTML in ihrem Code verwenden.

Oder man regt sich einfach in einem Forum seiner Wahl darüber auf. Sinn = 0, da es weder an a) noch an b) etwas ändern wird.

Die Frage in diesem Thread war: "wozu HTML in Javadoc", diese Frage wurde mehr oder weniger schon beantwortet. Um sein Programm zu kommentieren werden Kommentare benutzt. Um daraus eine schön formatierte HTML-Api-Beschreibung zu generieren, wird eben Javadoc benutzt.

EDIT: wenn man hier im Forum mit der Maus über "Javadoc" drüberfährt, sollte DAS die Frage endgültig beantworten, warum dort HTML benutzt wird.