[linux-l] API-Doc vs. Literate Programming (war: Warum gibt es keine einheitliche Dokumentation?)

[Volker Grabsch]

On Mon, Jan 01, 2007 at 09:03:32PM +0100, Steffen Dettmer wrote:
> * Volker Grabsch wrote on Sun, Dec 31, 2006 at 07:35 +0100:
> > On Thu, Dec 28, 2006 at 05:36:43AM +0100, Steffen Dettmer wrote:
> > > Gibt es ein Dokusystem für Sourcecode-Dokumentation, was Java, Python,
> > > C, C++ und Perl Doku nach plaintext/man, LaTeX/PDF kohärent erzeugen
> > > kann?
> > 
> > Das ist nicht unbedingt nötig. Ein Tool für jede Sprache wäre ja auch
> > schon super, solange man sich auf das Ausgabeformat einigt (z.B. eine
> > Manpage pro Funktion oder sowas, wie bei den System-Calls).
> 
> Der Vorteil wäre, dass man einfach verlinken kann.

Stimmt, das ist sehr wichtig. Dazu ist es aber nicht nötig, dass die
Doku aus einem API-Doc-Tool kommt. Und falls doch, dann ist der Schritt
zum Literate-Programming auch nicht mehr weit, wenn nämlich auch die
"Gesamt-Doku" entsprechend verlinken können muss.

Will sagen: Ganz oder gar nicht.

Entweder alles miteinander verlinkbar machen (Von der Python-API-Doc zur
Howto zur Java-API-Doc und wieder zurück). Dann braucht man aber kein
einheitliches API-Doc-Tool, sondern ergänzt die bestehenden um die
(standardisierten) Verlinkungs-Möglichkeiten.

Oder wirklich *alles* aus einem Tool, dann aber auch die Howto, etc.
wo man dann fast bei Literate-Programming angelangt wäre. Dann braucht
man die bestehenden Tools nicht um Kreuz-Links zu erweitern, weil eh
alles aus einem Werkzeug kommt.

> > Daher ist es IMHO nicht so wichtig, ob ein API-Doc-Tool nun alle
> > Sprachen unterstützt, oder gar vereinheitlicht. Es ist nicht wichtig,
> > ob die Python- und die Java-API-Doc gleich aussehen, sondern ob die
> > Python-API-Doc für einen normalen Python-Programmierer gut lesbar ist,
> > und die Java-API-Doc für einen normalen Java-Programmierer wie gewohnt
> > aussieht.
> 
> Doch, wenn ich ein Projekt in drei Sprachen implementieren, ziehe ich
> vor, wenn die Doku in einem Format kommt. Warum soll eine Erklärung für
> eine Python-Funktion unbedingt anders aussehen, als eine für Java?

Warum sollte der Python-Teil des Projektes für Python-Programmierer
ungewohnt dokumentiert sein, oder der Java-Teil für Java-Programmierer
ungewohnt? Das könnte man genauso fragen.

Natürlich wiegen diese Fragen nicht so schwer wie z.B. bei einem reinen
Python oder reinen Java-Projekt, da stimme ich dir zu.

> > [Doxygen]
> > >   Ich habe ähnliche APIs in C++ und Java. 
> > 
> > Das heißt, schreibe *eine* Doku, die beide APIs erklärt, und ggf. auf
> > Unterschiede hinweist. [...] Aus diesem gemeinsamen Dokument (das auch
> > aus mehreren Dateien bestehen kann) generierst du dann C++ und
> > Java-Dateien, die du dann in den Compiler jagst.
> 
> Das klingt unrealistisch aufwändig...

Das ist es nicht unbedingt. Man muss es halt probieren. Das erstmal
aufzusetzen ist vielleicht haarig, aber letztendlich geht es z.B., indem
du die Doku in LaTeX schreibst und entsprechende Kommentare an die
Code-Schnipsel setzt.

Ein Script, das diese Kommentare rausholt und für Compiler aufbereitet
ist auch kein Ding. (z.B. 10 Zeilen in sed, oder so)

Die Beispiel-Codes direkt als Testprogramme zu nehmen, das ist auch noch
vertretbarer Aufwand, zumal es z.B. für Python sowas schon fertig gibt
(doctest). Das erhöht auch wieder die Qualität und spart auf Dauer
Arbeit.

Sowas für ein konkretes Projekt aufzusetzen, sodass es wirklich nur
das leistet was man braucht, müsste in ein paar Arbeitstagen zu schaffen
sein, bei einem größeren Projekt also Peanuts.

Vielleicht ein Problem: Der Compiler meckert an einer bestimmten Zeile,
aber ich will ja eigentlich die *tatsächliche* Zeile im *echten* Quellcode
haben, nicht im generierten Code. In C gibt's dafür entsprechende
Präprozessor-Befehle, soweit ich weiß. In Sprachen wie Java kann man sich
retten, indem man einfach lange leere Kommentare einfügt, sodass die
Zeilenzahl stimmt. (in sed wäre das vielleicht eine Zeile Mehraufwand)

Die Compilerausgabe kann man dann auch noch manupulieren, sodass Tools
wie Eclipse oder Vim nicht zur Zeile 1354 in "myprog.java", sondern zur
Zeiel  1354 in "myprog.tex" springen. Auch das kann man im Makefile
zentral in wenigen Zeilen regeln.

Java will eine Datei pro Klasse haben, das ist kann es ja ruhig. Zur
Not besteht dann die Doc ebenfalls aus einer Datei pro Klasse. Das muss
ja nichtmal ein Nachteil sein. Auch hier noch kein ernsthaftes Problem.

Vielleicht macht "noweb" das alles sogar schon, vielleicht sogar auf
eine elegantere Art und weise. Keine Ahnung.

Dieser einmalige Aufwand sollte bei großen Projekten die eingesparte
Redundanz locker wett machen. Und die vielen Fehler in der Doku, denen
man vorbeugt! Vorallem ist auch die Motivation viel höher, etwas besser
zu dokumentieren, wenn die Doku nicht so weit vom Quelltext entfernt
ist. (Diese Grundidee steckt letztlich auch hinter den Docstrings und
hinter Quelltext-Kommentaren im Allgemeinen)

Den technischen Aufwand würde ich also gar nicht so groß ansehen,
und selbst wenn das nur aus gehackten Scriptz :-)  besteht: Die sind
ja nicht allzu groß, und auch wenn es in keiner Weise für andere Teams
wiederverwendbar ist, so kann man es zumindest selbst wieder für
ähnliche Projekte verwenden.


Nein, den *eigentlichen* Aufwand sehe ich eher in der Umgewöhnung. Muss
man ein Team davon erst einmal großartig überzeugen, hat man verloren.
Es gibt vielleicht sogar (firmen-)politische Widerstände. In einem
kleinen, enthusiastischen Team sollte das aber möglich sein.



> 
> > >   API Docs haben auch schon zwei Hauptzielgruppen: Benutzer (mit
> > >   Unterzielgruppen) und Libentwickler.  Letzere möchten auch Infos, wie
> > >   die Funktion heute gerade zufällig arbeitet, was die Benutzer gerade
> > >   nicht wissen sollen.
> > 
> > Unterschiedliche Detail-Level. 
> 
> Nein, eben nicht!
> 
> Ziel der Benutzer-Dokumentation ist, interna nicht zu dokumentieren,
> weil der Benutzer das nicht wissen soll, damit er sich nicht drauf
> verlassen kann.
> 
> Für Libentwickler müssen natürlich genau die interna dokumentiert werden
> - dafür interessieren ihn Beispielprogramme und update-Hinweise
> vielleicht nicht.

Ich verstehe den Zusammenhang nicht. Zuerst sagst du, es sind nicht nur
unterschiedliche Detail-Level. Danach sagst du, dass bestimmte Bereiche
nur in die Benutzer-Doku kommen und andere nur in die Entwickler-Doku.
Entspricht das nicht gerade dem Ein- und Ausblenden von Details?

Ganz leicht kann man es sich machen, wenn es nur eine Druck-Doku gibt,
und man diese in LaTeX schreibt: Benutze zwei Makros:

    \useronly{...}
    \devonly{...}

In der Userdoku definiere sie als:

    \newcommand{\useronly}[1]{#1}
    \newcommand{\devonly}[1]{}

In der Entwicklerdoku definiere sie als:

    \newcommand{\useronly}[1]{}
    \newcommand{\devonly}[1]{#1}

So leicht kann das gehen. Oder man nimmt halt Spezialkommentare und
die Generierungs-Scripte kümmern sich darum.

Natürlich ist das nur spekulativ, da ich hier kaum praktische Erfahrung
vorweisen kann. Deshalb würde mich sehr interessieren, ob das hier
wirklich nicht reicht, um zwei verschiedene API-Docs zu erzeugen, und
wo man Denkfehler liegt (d.h. welche Details ich eventuell zu stark
vereinfacht habe).


> > Das ist ja nun wirklich das geringste Problem. Im
> > Literate-Programming-Ansatz aber automatisch mit enthalten.  Dann
> > generierst du eben nicht eine Doku und das C++/Java-Zeugs, sondern 2
> > Dokus und das C++/Java-Zeugs. :-)
> 
> Ja klar, wenn man was generieren kann, geht sowas sicherlich. Vielleicht
> hat man noch unterschiedliche Sprachen etc.

Gerade bei unterschiedlichen Sprachen möchte man die Übersetzungen
einzelner Absätze doch beisammen halten, um zu verhindern, dass sie
auseinander driften, oder?

Obwohl der Ansatz von GNU-Gettext auch seine Berechtigung hat, und
dieses Detail regelt, ohne dass der Übersetzer mit Programmcode in
Berührung kommt. Das ist aber eher bei den String im User-Interface
sinnvoll, denn der technischen Dokumentation *will* man ja gerade als
Übersetzer auch den Quellcode vor sich haben, und nicht nur blind einen
englischen Text Satz für Satz übersetzen.

Vielleicht irre ich mich da aber auch. Wenn jemand damit Erfahrung hat,
würde mich das sehr interessieren.


> > Was auch nett ist, und mit vorhandenen Mitteln funktioniert: Pack
> > diese Details einfach in die privaten Funktionen/Methoden. Zumindest
> > EpyDoc kann sowohl "public" als auch "private" Varianten der Doku
> > erstellen.
> > 
> > Wobei in "private" halt auch alle internen und versteckten Attribute,
> > Funktionen, etc. auftauchen. In JavaDoc/Doxygen geht das doch auch,
> > oder?
> 
> Doxygen kann das definitiv, find ich aber doof.
> 
> Dokumentationsstruktur hat IMHO nichts mit Klassenstruktur zu tun. APIs
> "per Funktion" bzw. "per Methode" zu dokumentieren, ist oft doof. Das
> sieht man an der offiziellen JavaDoc gut. Das Interessante steht meist
> in packages oder classes.

Das stimmt auch wieder.

> Dass "String message" die Nachricht ist etc
> ist meist nicht so überraschend...

Ja, das ist schade, wenn da nur Offensichtliches steht. Aber man kann
genauso gut auch auf Gefahren hinweisen, die genau mit dieser Methode
zusammenhängen. Oder Beispiele liefern, die interessante Randfälle der
Methode/Funktion beleuchten. Sowas spezielles passt nicht in eine
Klassen- oder Paket-Doku. Gerade dafür gibt's ja die funktionsbasierten
Docstrings.


> Natürlich kann so eine Aufteilung manchmal helfen, klar. Allerdings hat
> man ja oft ganze Klassen, die Implementierungsdetails darstellen (und in
> der Benutzerdoku maximal als "Do not use" auftauchen).

Bei EpyDoc landen die internen Python-Module und -Klassen im
private-Teil und werden als Ganzes aus der public-Doku entfernt.

Das ist es doch, was du meinst, oder? Schade, dass man in Java
keine Klassen / Module / Pakete als "intern" markieren kann. In C++
geht das ja wieder, da sind das einfach alle Klassen, die nicht im
Haupt-Header auftauchen. Das ist nicht schön, aber prinzipiell geht's.
Oder kann Doxygen damit nicht umgehen?

> Methoden müssen
> vielleicht auch public sein, weil bestimmte andere libs diese Aufrufen
> können müssen. Die Sichtbarkeitsregeln sind ja sehr primitiv (public,
> protected, private z.B.).

In C++ gibt's genau dafür friend-Klassen. In Java hat man natürlich ein
Problem.

> Da sollte man nicht auch noch die Doku dran
> festmachen. Oft gibts viele public Methoden, von denen der Benutzer im
> "Normalfall" nur eine Handvoll aufrufen "sollte". Aber manchmal braucht
> er vielleicht auch mehrere, besonders bei libs auf einer höheren Ebene
> oder so.

Klingt mehr nach mangelnden Ausdrucksmitteln der Programmiersprache als
nach Dokumentations-Problemen.

Dies spricht jedoch umso mehr für den Literate-Programming-Ansatz statt
für Doxygen. ;-)


> > >   "Perfekte Beispiele" zu finden, geht auch nicht - irgendeinem fehlt
> > >   "seins" ja immer.
> > 
> > Ich sprach nur von *guten* Beispielen. (Aber vom perfekten Programmierer ;-))
> 
> Na, ich wollte darauf hinaus, dass man es nicht (nur/vollständig) über
> Beispiele sinnvoll dokumentieren kann.

Das stimmt. Aber didaktisch gesehen sind Beispiele verdammt wichtig. Ich
würde sogar behaupten, die Erklärungen brauchen nicht so genau und exakt
sein, können leichter verständlich formuliert und kürzer gefasst werden,
wenn man die Randfälle einfach durch guten Beispiel-Code erklärt.

Man sollte ja eh für jeden Teil der Doku das geeignete Ausdrucksmittel
verwenden. (Fließtext, Tabellen/Listen, Skizzen, Beispielcode)


> > Außerdem haben Beispiele didaktischen Wert, d.h. sie sollten Teil der
> > Erklärung sein oder zumindest interessante Randfälle beschreiben.
> 
> Didaktisch, genau. Ich find, der Normalfall sollte sein, dass Beispiele
> einen (den) Standardanwendungsfall zeigen, oder einen "Gutfallablauf"
> oder sowas in der Art. So sieht man oft gleich, wie ungefähr das
> funktioniert und hat einen prima Startpunkt.

Genau. Aber das vermisse ich in den meiden Dokus.

Gelten die Beispiele zudem als Testfälle, merkt man schon bei Schreiben,
wenn die nicht okay sind. Kaum einer testet jeder Änderung am
Beispielcode in der Doku nochmal extra aus ... leider ... mit
entsprechenden Ergebnissen  :-(

Wenn sie außerdem gleich als Testcode dienen, hat man eher die
Motivation, viele zu schreiben, weil man dann die (meist
umständlicheren) Unit-Tests sich sparen kann. So profitiert jeder
davon.

(Ja, ich bin ziemlich begeistert von Pythons doctest, das ist eine sehr
kreative, einfach geniale Idee gewesen.)


> > >   Didaktisch gut heisst oft, die API aus praktischer Benutzungssicht
> > >   zu beschreiben. Das ist aber ungünstig als Referenz... 
> > 
> > Ich sehe da keinen allzu großen Widerspruch. Natürlich ist die API-Doc
> > hauptsächlich eine Referenz. Aber ganze Klassen oder Module haben doch
> > ebenfalls Kommentare, und die kann man super nutzen für einführende
> > Worte und kleine Gesamt-Beispiele.
> 
> Ja, genau. Aber hier gibt es Grenzen. Doxygen kann immerhin "pages",
> schon mal sehr schön, nur leider sind die "Anhang". Aber in hypertext
> Dokumenten (PDF, HTML) ist das Recht egal. Doxygen kann eine "mainpage",
> ganz wichtig. Die kann man gliedern. Allerdings kommt dann hier ein
> "Grossteil" der "wichtigen" Doku rein. Gleichzeitig schränkt einen
> Doxygen ein: Tabellen sind immer einfach und schlicht, Grafikeinbindung
> ist mindestens "umständlich" usw. Da hat man dann oft neben der
> Doxygen-Doku weitere Dokumente. Eine Spezifikation (im Prinzip oft die
> API ohne Details, wenn die API gut aber knapp ist), vielleicht noch was
> mit Hintergrundinfos zum Lösungsansatz etc. 

Das sind aber Doxygen-spezifische Probleme.

Ein selbstgestricktes Literate-Programming würde dir technisch alle
Freiheiten geben, die du brauchst.

Gibt es auch *grundsätzliche* Probleme, wegen denen die Benutzung einer
API nicht gemeinsam mit der Referenz geschrieben werden kann/sollte?


> Meiner Erfahrung nach macht sich folgendes gut:
> 
> - Powerpoint (od ähnl) Präsentation mit Überblick, Marketing-Charakter,
[...]
> - Eine Webseite, wo man abschätzen kann, ob und wie das hinter dem
[...]
> - Release Notes.
[...]
> - Allgemeine (untypisierte) Infos. Kann ein Dokument oder auch eine
>   Webseite sein - oder ein README oder INSTALL. 
[...]
> - nu endlich kommt API docu :-)
[...]
> - Historie der Software nicht (kaum) in den Sourcen selbst sondern im
>   SCM (CVS, SVN).
> 
> Hat man libs, wo zu erwarten ist, dass sie von vielen Entwicklern
> genutzt wird, lohnt sich aufwändige Doku um so mehr. Vielleicht sogar
> Tutorials für Leute bestimmter Erfahrungen. Für eine GUIs könnte man das
> für Kenner von xlib und QT in zwei "Quickstarts" erklären oder sowas. Da
> will man sicherlich auch ein anderes Dokument.
> 
> Stellt sich wieder die Frage, ob das noch alles von einem Tool gemacht
> werden kann.

Nein, ich denke, das ist machbar. Statt Powerpoint kannst du genauso
auch PDF erzeugen, also läuft's letztlich auf LaTeX, HTML und Plaintext
als Dateiformat hinaus, wenn's nicht zu sehr verspielt sein soll.
Die Werkzeuge sind alle da, nur den Klebstoff muss man sich hacken.
Und das ist dann dein "Tool". Die Frage, die *ich* mir stattdessen stelle:

Kann das alles aus einer Quelle erzeugt werden?

Das heißt, kann man wirklich Redundanzen vermeiden? Kann man ganze
Formulierungen und Absätze wirklich wiederverwenden?


Ich meine, es wäre doch cool, wenn die Präsentation ein Stück
Beispielcode mit etwas Erklärung einbinden könnte, und dieses wirklich
aus der Doc stammt, also von API-Doc-Korrekturen automatisch mit
profitiert. Mehr Konsistenz, weniger Redundanz.

Doch selbst, wenn irgendwas aus politischen oder Marketing-Gründen in
zwei verschiedenen Varianten geschrieben werden muss: Auch hier wäre
es ja von Vorteile, einander entsprechende Absätze zusammen zu halten,
ähnlich wie bei den in verschiedenen Sprachen.

Aber das ist wirklich die Frage: Geht das? Ist das machbar? Oder gibt es
"äußere Kräfte", die die Redundanz einfach erzwingen, und dafür sogar,
dass Redundanz und Konsistenz-Probleme zu weniger Aufwand führen als
eine Vereinheitlichung? Das wäre mal interessant herauszufinden.


> > Schau dir mal eine kleine Vorzeige-Lib von mir an. Sie ist nicht
> > perfekt, demonstriert aber recht gut das Zusammenspiel von (Test-)
> > Beispielen, Doku und Plaintext:
> > 
> >     http://www.profv.de/vopu/
> > 
> > Schau dir sowohl den Quellcode als auch die erzeugte API-Doc an.
> > Beachte auch den "private"-Bereich der generierten Doku.
> 
> Quellcode? Phyton? Sorry, zu faul gerade :)
> 
> http://www.profv.de/vopu/doc/private/vopu-module.html
> 
> macht einen wirklich tollen Eindruck für eine API Doku. Aber mehr ist es
> leider auch nicht. Für eine komplette Vorzeige Doku würden mir noch
> einige Sachen fehlen. Beispielsweise warum es OrderedByCreation gibt.

Stimmt, inhaltlich kann man noch so einiges ergänzen.

Die Ursache ist eher ein Python-Interna, das man erst zu spüren bekommt,
wenn man mit Metaklassen arbeitet.

Es gibt eine Bibliothek, die es tatsächlich benutzt. Dort habe ich es
genauer/anschaulicher erklärt. Aber diese habe ich noch nicht
veröffentlicht.

Das Problem ist, in "OrderedByCreation" müsste ich ein fiktives
Anwendungsbeispiel finden, und es gibt kein solches Beispiel, das klein
und leicht verständlich ist, bis auf eben diese andere Bibliothek.
Aber vielleicht fällt mir ja noch was ein. Danke erstmal für den
Hinweis. Vielleicht könnte ich erwähnen, dass man das sinnvollerweise
irgendwohin mit "reinerbt" (Mehrfachvererbung).

Bis dahin genügt eigentlich der Hinweis: Wenn du eine "OrderedByCreation"-
Klasse brauchst, merkst du das auch.  :-)


> Wenn ich Entwickler bin, frage ich mich vielleicht, wie ich
> camelcase um einen Parameter erweitere, der angibt, ob der erste
> Buchstabe klein sein soll (oder weiss ich was). Über interna steht da
> nichts (was ja auch gut so ist, ist ja eine Benutzer Doku).

Das finde ich nicht. Die Implementierung ist ein 1-Zeiler, und
vollkommen "straight forward". Eine solche "Erweiterung" schreibt
man am besten, indem man eine zweite Funktion schreibt, die die
erste aufruft und beim Ergebnis das erste Zeichen auf Lowercase setzt.

Die meisten Routinen haben eine überraschend einfache Implementierung.
Das ist eine sehr schöne Eigenschaft von Python. Schau dir wirklich mal
den Quellcode an. Nicht durcharbeiten, sondern einfach nur überfliegen:

    http://www.profv.de/vopu/vopu.py

Die Docstrings sind im Schnitt 3-4 mal so groß wie die Implementierung.


> Allgemeines steht da auch nicht. Wann wurde das entwickelt,

Ist das wichtig? Na gut, dass es für Python-2.4 geschrieben ist, sollte
noch dastehen. Aber ansonsten ist da die Jahreszahl bei der Copyright-
Angabe? Braucht man mehr?

> welche Version ist das,

In der Modul-Doku findest du

    __version__    "1.7"

Das ist wohl eine Konvention. Warum EpyDoc das nicht auswertet, weiß ich
nicht. Vielleicht sollte ich das wirklich lieber in den Modul-Docstring
hinein schreiben.

> warum wurde die verwendete Abstraktion gewählt (die
> mich z.B. überrascht hat, sehe keinen Zusammenhang zwischen den
> Funktionalitäten.

Den gibt es auch nicht. Eines der Beispiele kombiniert wohl zwei der
Klassen, aber das ist eher Zufall.

Gleich der erste Satz der Modul-Doku sagt doch:
| This module contains various functions and classes which are very
| useful for my daily work with Python.

Es ist also ein Sammelsorium von Hilfs-Klassen und -Funktionen, die
man wiederverwenden könnte. Zum Teil sind es einfach Sachen, die es in
den entsprechenden Python-Paketen einfach nicht gibt, obwohl sie
praktisch wären.


> Die Sourcen guck ich mir nicht weiter an, hab eh
> keinen Plan von phyton. Obwohl ich mich z.B. Frage, ob es den Aufriss
> eines StrinStreams Wert ist, der scheinbar nur "self.content += str"
> implementiert (falls ich die Sourcen richtig verstehe, was mangels
> Python Kenntnissen recht unwahrscheinlich ist).

Nein, das hast du völlig richtig erkannt. Die Implementierung ist
trivial, aber solch eine Klasse gab es in Python noch nicht
(mittlerweile glaubich gibt's das schon). Das Interface ist
entscheidend.

Es gibt Funktionen, die wollen etwas ausgeben, in bieten es leider
nur an, in eine Ausgabedatei (genauer: einen Stream) zu schreiben.
Will ich lieber einen String, brauch ich solch eine Hilfsklasse.
Als ich sie geschrieben hatte, fiel mir auf, dass sie mit dem konkreten
Projekt eigentlich nichts zu tun hat. Und genau solche Dinger schiebe
ich nach VoPU, dafür ist es da. :-)

Auf die gleiche Art und Weise ist übrigens damals auch VoJI entstanden,
wo ich jedlichen "generischen" Programmcode hingeschoben habe, der in
Wahrheit nur fehldende Java-Features darstellt:

    http://voji.sourceforge.net/

Bei VoJI hab ich aber erst spät mit dem Dokumentieren angefangen.
Eigentlich nur bei voji.report und voji.utils:

    http://voji.sourceforge.net/voji-1.1/doc/voji/report/package-summary.html
    http://voji.sourceforge.net/voji-1.1/doc/voji/utils/package-summary.html

Viele der Funktionen und Klassen von VoJI gibt es mittlerweile, in etwas
anderer Form, auch in der Java-API. Damals aber noch nicht.


> Bei camelcase verstehe ich (der den Ausdruck nicht kannte) die Funktion
> sogar nur über die Beispiele - find ich suboptimal (sollte beides
> gehen).

Ich könnte einen Link zur Wikipedia einbauen. ;-)

> Natürlich auch nur wenn man erwartet, dass jemand die Funktion
> benutzt, ohne die Hintergründe schon zu kennen. Wenn man eine solche
> Ausbildung vorraussetzt, braucht und sollte man das natürlich nicht
> dokumentieren.

Eben. Wieso sollte jemand diese Funktion jemals gebrauchen können,
wenn er nichtmal weiß, was CamelCase ist.

Ich meine, wenn ich den Newton-Algorithmus implementiere, sollte ich
doch auch vom Leser erwarten, dass er weiß, was die Nullstelle einer
Funktion ist. Und ich erkläre auch nicht Newton-Algorithmus (höchstens
ein Link zur Wikipedia ;-)), sondern ich weise höstens auf nummerische
Details hin, die nicht so klar sind, wenn man nur den Newton-Algorithmus
in der Theorie kennt. Oder irgendwelche Java-typischen Probleme, die
es in dem Zusammenhang gibt.

Aber die Erklärung, was eine Funktion ist, was eine Nullstelle ist,
wie und warum der Newton-Algorithmus funktioniert, all das gehört doch
ausgelagert. Das hat doch nichts mehr mit dem Programm zu tun.

Wenn meine Zielgruppe das jedoch nicht wissen sollte, dann würde ich
einen gesonderten Abschnitt mit mathematischen Grundlagen in die Doku
einfügen und auf diesen verweisen. Dann kann sich ein Neuling
systematisch die mathem. Grundlagen auf einmal anlesen, statt bei
jeder Funktion auf chaotische Weise immer mehr Details zu erfahren.

Genauso sollte es meiner Meinung nach auch mit GUI-Grundlagen geschehen,
also dass man zwischen Eingefeldern mit TAB wechseln kann, dass man auf
Buttons draufklicken kann, dass ein Label das danebenstehende Textfeld
beschreibt, dass das Kreuz in der Ecke das Fenster schließt, u.s.w.


> Release-Informationen fehlen völlig (welche Version, von wann,
> freigegeben oder experimentell, getestet oder nicht, welche
> Qualitätsanforderungen, welche Sprache überhaupt usw. Welche Funktionen
> würde ich hier hinzufügen, welche anderen hingegen wären hier eher
> falsch einsortiert etc.

Danke für den Hinweis. Aber ehrlich gesagt wüsste ich nicht, was ich zu
diesen Punkten schreiben sollte.
(Und die Versionsnummer steht ja da)

> (Das kommt wohl daher, dass es einfach eine
> unsystematische Sammlung von Funktionen ist, die nach ihrem Autor
> gruppiert sind, was normalerweise natürlich keinen Sinn macht).

Genauso ist es.

> Macht hier "für Dich" natürlich keinen Sinn, Du weisst das ja auswendig
> bzw. spielt es keine Rolle (das gilt vermutlich für die gesamte Doku
> ;)), aber wenn andere die Lib nutzen wollen würden, fehlten halt noch
> viele Infos.

Achso? Wenn ich eine fremde Lib benutze, schaue ich kaum auf diese
Dinge. Ich schaue auf die Lizenz (ob ich sie überhaupt nutzen *darf*),
später vielleicht auf die Versionsnummer (wenn ich sie auf verschiedenen
Rechnern vorfinde), und in die Doku/Howtos, ob sie überhaupt das macht,
was ich brauche.

Sicher ist auch der Status (stable/...) interessant, aber doch erst bei
großen Projekten, oder?


> Es gibt keine Suche, dass ist bei einem "Webserver-Dienst" eigentlich
> Schade. Der Index enthält neben vielen komischen (privaten?) Funktionen
> (?) und viele __init__s nicht einen "menschlich-aussehenden Begriff".

__init__ ist der Konstruktor. Das weiß aber ein Python-Programmierer.
Auch __cmp__, __delattr__, etc. kennt jeder. Das sind überladene
Operatoren.

Jedoch tauchen im Index z.T. builtin-Klassen von Python auf, nämlich
die, von denen ich meine eigenen Klassen abgeleitet habe. Mit Docstring
und allem drumherum. So kann man auch ohne Python-Doku schnell mal
nachlesen, was diese oder jene Basis-Klasse eigentlich tut, von der eine
der VoPU-Klasse erbt.

Im Index stört das natürlich eher, das ist wahr.

Die Grundidee dahinter finde ich aber gar nicht so schlecht. Das löst
das Problem, auf die offizielle Python-Doku zu verlinken. (man weiß
ja nicht, ob derjenige das online oder offline liest, und ob man auf
python.org muss, oder auf /usr/share/python...)


> Ich würde sowas wie "URL Verarbeitung" oder "Iterating objects" oder so
> erwarten. Man weiss ja oft weder, ob eine bestimmte "gesuchte"
> Funktion existiert, geschweige denn wie sie heisst...

Das verstehe ich nicht. Was meinst du mit "URL Verarbeitung" oder
"Iterating objects"?


> > Das sollte die Dinge besser verständlich machen, die ich hier mühsam
> > versuchte zu beschreiben. Literate Programming ist das nicht, aber
> > es demonstriert die Verbindung zwischen Einführung, Beispielcode
> > und Referenz.
> 
> Referenz sehe ich. "Beispielschnipsel" auch. Wirklich gut, prima. Für
> "richtige" Beispiele, die auch zeigen, warum man die wichtigen
> Funktionen wie benutzt etc., ist die Lib vermutlich zu trivial. Aber bei
> kleinen einfachen Funktionen ist es (entgegen DRY) oft doch eine gute
> Idee, die Funktion jeweils zu implementieren. Spart viele Abhängigkeiten
> von Libs für Dreizeiler und damit spart das auch schnell viel
> Wartungsaufwand (z.B. die alte lib kompiliert auf der neuen Zielplatform
> nicht, kein Maintainer mehr, ...).

Meine Applikationen nutzen in der Regel mehrere Funktionen der vopu.py,
und ich möchte, dass eine Applikation von den Verbesserungen einer
anderen profitiert, wenn sie möchte.

Daher mache ich das so: *In* die Applikation kommt eine Kopie der
vopu.py, es ist ja nur ein Modul, dem ist es egal, wo es liegt. Anhand
der VoPU-Versionsnummer weiß ich auch immer, womit ich es zu tun habe.

Entwickle ich die Applikation weiter, behält sie ihre alte vopu.py, das
erspart Kompatibilitäts- und Distributionsprobleme. Erst dann, wenn ich
für die Applikation eine neue VoPU-Funktion brauche oder schreibe,
kriegt diese eine Applikation eine aktuelle vopu.py.

Haben zwei Python-Pakete eine vopu.py, nimmt jede ihre eigene, denn
die vopu.py liegt ja im jeweiligen Package, also in einem eigenen
Verzeichnis und damit einem eigenen Namespace.

Das ist also sehr einfach gehalten, und auch für größere Libs wird
generell empfohlen, eigene Libs gebündelt mit der Applikation zu
vertreiben, solange, bis die Lib wirklich *sehr* weit verbreitet ist
und sich ein extra Paket lohnt. Das ist eine Python-Richtlinie, und
zwar meiner Meinung nach eine ziemlich gute. Kein Konflikte, keine
Kompatibilitätsprobleme.

Jede größere Applikation besteht zum Teil aus eigenen general-purpose-
Bibliotheken. Aber nur bei den wenigstens davon lohnt es sich wirklich,
sie getrennt zu vertreiben. Das ist ja immer sowohl technischer als auch
organisatorischer Mehraufwand.


Viele Grüße,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR