Generelle Frage zur Doku

Wenn du dir nicht sicher bist, in welchem der anderen Foren du die Frage stellen sollst, dann bist du hier im Forum für allgemeine Fragen sicher richtig.
Antworten
ChrisGTJ
User
Beiträge: 105
Registriert: Mittwoch 22. August 2007, 15:45

Hallo zusammen,

ich hatte beim Dokulesen das Gefühl, daß die Beschreibung der einzelnen Module unter http://docs.python.org/ nicht vollständig ist, daß nur quasi die "wichtigsten" (was immer das ist) Dinge beschrieben sind.

Weiß jemand, wie vollständig die Doku dort ist? Und wenn sie es nicht ist, weiß jemand eine gute Quelle, die die Module vollständig beschreibt?

Gruß und Danke,

Christoph
BlackJack

Im allgemeinen sind die Module vollständig beschrieben.

Ansonsten gibt's noch die Docstrings, die man sich im Interpreter mit `help()` oder mit `pydoc` anschauen kann und natürlich bei den meisten Modulen den Quelltext selbst.
CM
User
Beiträge: 2464
Registriert: Sonntag 29. August 2004, 19:47
Kontaktdaten:

Hallo,

ich halte die Pythondoku auch für sehr vollständig und bin - inzwischen sehr, sehr zufrieden. Aber ich kann mir schon vorstellen, daß gerade Anfänger darunter leiden, daß es zu wenige Beispiele gibt und dergleichen Dinge mehr. Das ist allerdings eine völlig subjektive Interpretation Deiner Frage, ChrisGTJ. Falls Du zur Verbesserung der Doku beitragen willst, so geht das auch. Hier ist beschrieben, wie:
http://www.python.org/dev/doc/

Gruß,
Christian
ChrisGTJ
User
Beiträge: 105
Registriert: Mittwoch 22. August 2007, 15:45

CM hat geschrieben:Hallo,

ich halte die Pythondoku auch für sehr vollständig und bin - inzwischen sehr, sehr zufrieden. Aber ich kann mir schon vorstellen, daß gerade Anfänger darunter leiden, daß es zu wenige Beispiele gibt und dergleichen Dinge mehr. Das ist allerdings eine völlig subjektive Interpretation Deiner Frage, ChrisGTJ. Falls Du zur Verbesserung der Doku beitragen willst, so geht das auch. Hier ist beschrieben, wie:
http://www.python.org/dev/doc/

Gruß,
Christian
Beispiele sind allerdings zweischneidig, oder? Klar, machen sie einiges deutlich, tragen aber auch zur Verwirrung bzw. zu unübersichtlicher Doku bei...

Danke für den Hinweis, wenn ich etwas finde, wo ich helfen kann, dann lange ich auch mal zu.

Gruß,

Christoph
EnTeQuAk
User
Beiträge: 986
Registriert: Freitag 21. Juli 2006, 15:03
Wohnort: Berlin
Kontaktdaten:

ChrisGTJ hat geschrieben:Beispiele sind allerdings zweischneidig, oder? Klar, machen sie einiges deutlich, tragen aber auch zur Verwirrung bzw. zu unübersichtlicher Doku bei...
Auch nicht unbedingt. Denn hier setzt wieder der bekannte Spruch an, "Man kann es nicht allen recht machen". Einige lernen durch sture Theorie, andere durch Beispiele und Ausprobieren.
ChrisGTJ hat geschrieben: Weiß jemand, wie vollständig die Doku dort ist? Und wenn sie es nicht ist, weiß jemand eine gute Quelle, die die Module vollständig beschreibt?
Grundlegend ist die Dokumentation komplett. Jedoch gibt es ja nicht nur ein paar Module sondern eine ganze Menge. Weiterhin gibt es auch entsprechend viele Entwickler. Und ich gehe stark von aus, das die Dokumentation zum großteil von diesen auch geschrieben wird, was bedeutet, dass der eine mehr auf die Dokumentation achtet, der andere weniger.
So gibt es auch Module, welche erst später in den Kern aufgenommen wurden. So ist die Dokumentation von xml.etree auf die wesentliche API reduziert. Schaut man auf die Internetseite des Autors, bekommt man eine ganze Menge Extra, Beispiele uvm.

Hier finde ich, währe eine riesen Erweiterung, externe/weitere Informationen mit einzubinden. Ob via Link oder in erweiterter Fassung übernehmen, ist die andere Frage.

Aber es wird sich vieles für die nächsten Versionen ändern, wie die aktuelle Dokumentation von Python 2.6 zeigt: http://docs.python.org/dev
Hier kannst du gerne deine ganzen kommentare loswerden. (Besonders, da man jetzt einzelne Abschnitte direkt online dokumentieren kann)


MfG EnTeQuAk
Benutzeravatar
birkenfeld
Python-Forum Veteran
Beiträge: 1603
Registriert: Montag 20. März 2006, 15:29
Wohnort: Die aufstrebende Universitätsstadt bei München

CM hat geschrieben:Hallo,

ich halte die Pythondoku auch für sehr vollständig und bin - inzwischen sehr, sehr zufrieden. Aber ich kann mir schon vorstellen, daß gerade Anfänger darunter leiden, daß es zu wenige Beispiele gibt und dergleichen Dinge mehr. Das ist allerdings eine völlig subjektive Interpretation Deiner Frage, ChrisGTJ. Falls Du zur Verbesserung der Doku beitragen willst, so geht das auch. Hier ist beschrieben, wie:
http://www.python.org/dev/doc/
Ouh, das ist ja völlig outdated. Ich kümmere mich darum.
Dann lieber noch Vim 7 als Windows 7.

http://pythonic.pocoo.org/
ChrisGTJ
User
Beiträge: 105
Registriert: Mittwoch 22. August 2007, 15:45

So, dann mal ganz konkret:

Ich suche Info über das Statement "staticmethod" bzw. darüber, ob es ein Analogon "staticvariable" gibt. In der oben genannten Quelle finde ich nichts, wenn ich den Index bemühe.

(google verrät mir, daß es das nicht gibt, aber da ich schon "staticmethod" nicht gefunden habe, hat das alleinige Fehlen von "staticvariable" in der Doku keine Aussagekraft).

Auch über "property" schweigt sich die Doku beispielsweise aus.

Ich bin kein Softwaretheoretiker, insofern fehlt mir das Wissen, zu entscheiden, ob der Begriff "Statement" überhaupt richtig gewählt ist für die Buchstabensammlung "staticmethod" ;). Soll heißen, ich stehe der Hilfe etwas hilflos gegenüber, weil ich raten muß, in welchem Kapitel ich das gesuchte wohl finden könnte.

Hat jemand eine Idee, wo es eine in obigem Sinne vollständigere Doku gibt (google halte ich in dem Fall nicht für effizient)?

Gruß,

Christoph
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

ChrisGTJ hat geschrieben:Ich suche Info über das Statement "staticmethod" bzw. darüber, ob es ein Analogon "staticvariable" gibt. In der oben genannten Quelle finde ich nichts, wenn ich den Index bemühe.
Also wenn ich ``staticmethod`` in das Suchfeld auf docs.python.org dann kommt mir gleich beim ersten Hit die Dokumentation zu Built-In Functions in der ``staticmethod()`` beschrieben ist. ``staticvariable`` gibt es hingegen nicht: es ist nicht in der Dokumentation und wenn du dir die Builtins anzeichen lässt (``print __builtins__``) dann ist es auch nicht da.
ChrisGTJ hat geschrieben:(google verrät mir, daß es das nicht gibt, aber da ich schon "staticmethod" nicht gefunden habe, hat das alleinige Fehlen von "staticvariable" in der Doku keine Aussagekraft).
Wie du siehst, ist der erste Hit zu ``staticmethod`` gleich mal die Dokumentation.
ChrisGTJ hat geschrieben:Auch über "property" schweigt sich die Doku beispielsweise aus.
``property()`` istauf dergleichen Seite zu finden, die ich dir verlinkt habe, ebenfalls als erster auf der Suchseite.
ChrisGTJ hat geschrieben:Hat jemand eine Idee, wo es eine in obigem Sinne vollständigere Doku gibt (google halte ich in dem Fall nicht für effizient)?
Hat sich ja wohl erledigt, da Google ja doch effizient ist ;)
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
ChrisGTJ
User
Beiträge: 105
Registriert: Mittwoch 22. August 2007, 15:45

Urgsss, ich hasse es. Habe wohl Scheuklappen auf. Natürlich kenne ich die Startseite, ich bin dann nur in die Language Reference abgestiegen und da dann an die Grenzen gestoßen... Das Suchfeld oben rechts habe ich völlig ignoriert (Ha, habe einen Schuldigen gefunden: Wie kann man sowas auch nur rechts oben hinpacken... allerdings hätte ich es auch übersehen, wenn es rot blinkend in der Mitte gestanden hätte... ;) ).

Danke für Eure Geduld.

Christoph
BlackJack

Es ist auch kein Statement (deutsch Anweisung) sondern eine Funktion.
ChrisGTJ
User
Beiträge: 105
Registriert: Mittwoch 22. August 2007, 15:45

BlackJack hat geschrieben:Es ist auch kein Statement (deutsch Anweisung) sondern eine Funktion.
Wie gesagt, ich bin kein SW Theoretiker, obwohl die Schreibweise

property(...)

natürlich ganz klar macht, daß es eine Funktion ist. Aber für jemanden, der die Sache erstmal nur benutzen will, ist es völlig Wumpe, was es ist, solange es das tut, was es soll. Das Dingen kommt mit der Sprache Python und das Schlüsselwort "in" gehört genau so dazu wie die Funktion "range()". Kann sein, daß "range()" in einem Modul verborgen ist, das ich nicht notwendigerweise installieren muß, bei mir ist es installiert und somit gehört es dazu. Jedem "language lawyer" und jedem mit tieferen Einblick in die Struktur von Python mögen dabei die Haare zu Berge stehen, aber so funktioniert es nun mal häufig.

Christoph

PS: Ich will nicht bestreiten, daß es sehr sinnvoll ist, zu wissen was man tut und auch noch die Hintergründe zu kennen. Manchmal muß es aber beim bloßen Anwenden bleiben.
BlackJack

Der Unterschied kann auch in der Anwendung wichtig sein. ``print`` ist zum Beispiel eine Anweisung, mit der Konsequenz, dass man es zum Beispiel nicht umdefinieren kann und nicht in ``lambda``-Funktionen verwenden kann.

Die Worte die von Anweisungen verwendet werden sind allgemein reserviert, können in Python also nicht als Namen verwendet werden. Bei Sprachen wo so etwas möglich ist, kann man zum Beispiel so etwas schreiben:

Code: Alles auswählen

IF THEN THEN THEN = ELSE; ELSE ELSE = THEN
Gut geeignet um andere Leute zu ärgern, die solchen Quelltext irgendwann mal warten müssen. :-)
Antworten