Erste Schritte Javadoc Tool

[babuschka]

Hi,

ich hab zwar bisher noch keinen eigenen Java-Code geschrieben, bisher hab ich bloß Codebeispiele aus einem Lernbuch abgetippt, um auszuprobieren, ob's geht und um es erst mal zu verstehen.
Jetzt möcht ich aber auch schon anfangen, mir das Anlegen von Kommentaren anzueignen. Code ohne Kommentare ist für alle, die's lesen müssen, etwas scheußliches. Das Tool Javadoc, das aus speziellen im Code hinterlegten Kommentaren automatisch eine Dokumentation generiert, find ich ziemlich cool, damit schlägt man ja quasi zwei Fliegen mit einer Klappe.
Aber - wo krieg ich denn das, oder ist das in Eclipse schon drin? Wenn ja, wo find ich es? Als Download hab ich das bisher immer nur als Teil einer Komplett-Umgebung gesehen - aber da hab ich ja eh die neueste, die hab ich ja runtergeladen, um das Buch durcharbeiten zu können.
Danke vielmals!
Gruß,

Javaswillerdenn

 

[diggaa1984]

Menüpunkt "Project -> Generate Javadoc" 😱

 

[hüteüberhüte]

Wenn du mit Java programmierst, wirst du sicher schon das JDK installiert haben. Im bin/ Verzeichnis befindet sich das Tool javadoc

Btw.: How do I set or change the PATH system variable?
http://www.java-forum.org/einfuehru...umgebungsvariable-einstellen-windows-7-a.html

[EDIT]

javadoc: error - No packages or classes specified.
usage: javadoc [options] [packagenames] [sourcefiles] [@files]
-overview <file>          Read overview documentation from HTML file
-public                   Show only public classes and members
-protected                Show protected/public classes and members (default)
-package                  Show package/protected/public classes and members
-private                  Show all classes and members
-help                     Display command line options and exit
-doclet <class>           Generate output via alternate doclet
-docletpath <path>        Specify where to find doclet class files
-sourcepath <pathlist>    Specify where to find source files
-classpath <pathlist>     Specify where to find user class files
-exclude <pkglist>        Specify a list of packages to exclude
-subpackages <subpkglist> Specify subpackages to recursively load
-breakiterator            Compute 1st sentence with BreakIterator
-bootclasspath <pathlist> Override location of class files loaded
                          by the bootstrap class loader
-source <release>         Provide source compatibility with specified release
-extdirs <dirlist>        Override location of installed extensions
-verbose                  Output messages about what Javadoc is doing
-locale <name>            Locale to be used, e.g. en_US or en_US_WIN
-encoding <name>          Source file encoding name
-quiet                    Do not display status messages
-J<flag>                  Pass <flag> directly to the runtime system

Provided by Standard doclet:
-d <directory>                    Destination directory for output files
-use                              Create class and package usage pages
-version                          Include @version paragraphs
-author                           Include @author paragraphs
-docfilessubdirs                  Recursively copy doc-file subdirectories
-splitindex                       Split index into one file per letter
-windowtitle <text>               Browser window title for the documenation
-doctitle <html-code>             Include title for the overview page
-header <html-code>               Include header text for each page
-footer <html-code>               Include footer text for each page
-top    <html-code>               Include top text for each page
-bottom <html-code>               Include bottom text for each page
-link <url>                       Create links to javadoc output at <url>
-linkoffline <url> <url2>         Link to docs at <url> using package list at <u
rl2>
-excludedocfilessubdir <name1>:.. Exclude any doc-files subdirectories with give
n name.
-group <name> <p1>:<p2>..         Group specified packages together in overview
page
-nocomment                        Supress description and tags, generate only de
clarations.
-nodeprecated                     Do not include @deprecated information
-noqualifier <name1>:<name2>:...  Exclude the list of qualifiers from the output
.
-nosince                          Do not include @since information
-notimestamp                      Do not include hidden time stamp
-nodeprecatedlist                 Do not generate deprecated list
-notree                           Do not generate class hierarchy
-noindex                          Do not generate index
-nohelp                           Do not generate help link
-nonavbar                         Do not generate navigation bar
-serialwarn                       Generate warning about @serial tag
-tag <name>:<locations>:<header>  Specify single argument custom tags
-taglet                           The fully qualified name of Taglet to register

-tagletpath                       The path to Taglets
-charset <charset>                Charset for cross-platform viewing of generate
d documentation.
-helpfile <file>                  Include file that help link links to
-linksource                       Generate source in HTML
-sourcetab <tab length>           Specify the number of spaces each tab takes up
 in the source
-keywords                         Include HTML meta tags with package, class and
 member info
-stylesheetfile <path>            File to change style of the generated document
ation
-docencoding <name>               Output encoding name

[/EDIT]

 

[babuschka]

So weit so gut. Danke schon mal!
Jetzt bräuchte ich dazu nur noch so eine Art Tutorial, damit ich weiß, welche Kommentare wo im Code hingehören und wo sie dann auf der generierten Seite erscheinen - muss ja irgendwelchen Konventionen folgen, damit es funktioniert. Wahrscheinlich ist das drin, muss mal schauen.
Danke!
Gruß,

Javaswillerdenn

 

[hüteüberhüte]

Oh ja das ist schon fast eine eigene Philosophie. Danach einfach suchen, bzw. siehe hier: How to Write Doc Comments for the Javadoc Tool

Eigentlich ist alles, was in

    /**
     * Blabla.
     *
     * @return  blabla.
     */

vor einer Methode steht, wichtig.

 

[babuschka]

Danke, hüteüberhüte!

Die Seite werd ich mir also mal zu Gemüte führen. Ich dachte, das ist nur so, wie es bei Sun gemacht wird, vieleicht gibt's ja noch was anderes. Aber wenn das so der allgemeine Usus ist, dann werd ich mir das mal hinter die Ohren meißeln.
Gruß,

Javaswillerdenn

 

[fwp]

Moin moin,

habe eine Frage zum Formatieren von Kommentaren im JAVA-Code zur automatischen Generierung von Dokumentationen über Javadoc.

Wenn ich folgenden Java-Code schreibe

	/**
	 * Creates a new instance of Person by the given parameters.
	 * @param vorname        First name
	 * @param nachname       Last or christian name
	 * @param geschlecht     gender
	 * @param geburtsdatum   Date of birth
	 */
	public Person(String vorname, String nachname, Geschlecht geschlecht, Date geburtsdatum) {
		super();
		
		this.vorname = vorname;
		this.nachname = nachname;
		this.geschlecht = geschlecht;
		this.geburtsdatum = geburtsdatum;
	}

dann sieht der generierte Teil der Dokumentation so aus:

Creates a new instance of Person by the given parameters.

Parameters:

vorname First name
nachname Last or christian name
geschlecht gender
geburtsdatum Date of birth​

Kann ich diesen auch so formatieren lassen, dass die Parameter und deren Beschreibung spaltengerecht formatiert werden?

Creates a new instance of Person by the given parameters.

Parameters:

vorname . . . .. . . First name
nachname . . .. . . Last or christian name
geschlecht . . . . . gender
geburtsdatum . .. Date of birth​

Füge ich mehrere Leerzeichen (oder Tabulatorzeichen) ein, sodass es im Quellcode ordentlich aussieht, so werden diese Leerzeichen im Dokument "wegoptimiert". Ein Versuch mit   im Quellcode führt zwar zu einer ordentlichen Formatierung in der Dokumentation, erschwert aber die Lesbarkeit im Quellcode erheblich.

 

[maki]

Man kann mit [c]<pre> </pre>[/c] die Formatierung beibehalten (preserve?).

Allerdings solte man sowas imho nicht überall einsetzen um die gewünschte Formaierung zu erhalten, es gibt auch andere Doclets/Stylesheets die erzeugte JavaDoc eben anders aussehen lassen.

Nebenbei gesagt ist das JavaDoc Format recht alt und wird von jedem erfahreren Java Entwickelr vestanden, solltest dich hüten als Anfänger Dinge ändern zu wollen die einerseits schon sehr etabliert sind udn andererseits recht egal 😉

Nebenbei, Kommentare und JavaDoc sind nicht immer dasselbe, zuviele sog. "Inline Kommentare" werden als "Code smell" gehandelt, JavaDoc ist "echte" Dokumentation.

Ansonsten?
Wie fühlt es sich an für deutsch benammte Variablen englische Doku zu schreiben? 😉
Am besten beides in Englisch halten imho, zumindest aus Liebe zur deutschen Sprache, dann vermeidet man auch so tolle Denglisch-Konstrukte wie [c]getAlter();[/c]

"christian name"?
Was wenn die Person kein Christ ist und nie getauft wurde? 😉