Javadoc Comments: IllegalArgumentException deklarieren?

[hdi]

Hey,

kurze Frage: Mache ich in einem Javadoc Comment per @throws auf eine IllegalArgumentException aufmerksam? Ich denke eigentlich müsste es reichen wenn man die gültige Range für einen Parameter beim @param dazu schreibt oder? Aber ich hab in der Sun API schon gesehen dass auch unchecked Exceptions da aufgeführt werden, und bin mir jetzt nich sicher ob man das tun sollte oder nicht :bahnhof:

Danke!

edit: ach und wo wir grade dabei sind: Wenn ich extends oder implements habe, dann wird das automatisch rausgezogen aus der Definition und in der Doc angezeigt oder? Oder gibt es dafür auch irgendnen Befehl den ich den den JavaDoc Comment für die Klassendefinition schreiben muss?

 

[Soahc]

Das mit der IllegalArgumentException kommt darauf an, ob Du sie "thowst".. bei

/**
	 * Do any thing.
	 *
	 * @param s the s
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public void doAnyThing(String s) throws IllegalArgumentException {
		if (s.length()==0) throw new IllegalArgumentException("length of s is 0");
		//do...
	}

kommts mit in den JavaDoc und bei

/**
	 * Do any thing.
	 *
	 * @param s the s
	 */
	public void doAnyThing(String s) {
		if (s.length()==0) throw new IllegalArgumentException("length of s is 0");
		//do...
	}

nicht.
Bei Methoden, die ein Interface implementieren, kommt der Java-Doc in das Interface. Was Du mit Vererbung (extends) meinst, weiß ich jetzt leider nicht. Falls Du mit eclipse arbeitest kann ich Dir auf jeden Fall JAutodoc (JAutodoc - Eclipse Plugin) empfelen... damit kannst Du die korrekten Java-Doc Kommentar-Hüllen jeder Zeit automatisch in deinen Java-Dateien generieren lassen.

gruß, Soahc

 

[tfa]

Selbstverständlich kommt die Exception auch in die Java-Docs, wenn man sie nicht explizit deklariert (was bei unchecked nicht nötig, aber möglich ist). Dafür ist doch die Dokumentation da.

 

[Marco13]

Man könnte da IMHO auch pragmatisch sein: Wenn man bei @param Dazu schreibt: "The length of the string may not be 0" (oder so), dann bedeutet das IMHO: Wenn die länge 0 ist, ist das Verhalten unpsezifiziert - d.h. da kann "irgendeine" unchecked Exception fliegen, von NPE über AIOOBE bis IAE. Aber wenn man explizit überprüft, und das Teil des Vertrages sein soll, kan man auch dazuschreiben, welche es ist.