Was gehört alles in eine richtige Dokumentation?

[Furtbichler]

Zitat von r2c2:

Zitat:

Trotzdem würde ich auch bei einer eindeutig benamten Funktion, mit eindeutig benamten Parametern, eine Dokumentation erwarten.
Auch wenn in der Dokumentation "nur" in Prosa das steht, was man beim Namen der Funktion erwarten würde.

Einfache Frage: Warum?

Weil erstens eine System/API-Doku vollständig sein sollte und zweitens eine Doku erweitert werden sollte. Keine Doku wird selten erweitert. Eine API, die aus elementaren Operationen besteht, die aussagekräftige Namen haben ist selbsterklärend. Das ist die Krux bei guten API: Einerseits gehört die Doku dazu, weil dort eben auch steht, was für Seiteneffekte es gibt, Beispiele, Exceptions, der ganze Kram eben, Und da sieht es eben blöd aus, wenn in der Doku steht: "CreateForm: Guess what the function does..." oder "The name says it all" (obwohl, warum eigentlich nicht).

Ach, und die Sache mit der Rekusivität im Methodennamen kann man so sehen, muss man nicht, aber dein Einwand ist schon ok.