Das deutsche Python-Forum

Moin moin,

ich habe vor, eine kleine Diskussion zu starten Wie steht ihr hinsichtlicher der Dokumentation dazu, wenn es in einem Projekt Methoden und/oder Funktionen gibt, die Implementierungsdetails sind? Sollten sie überhaupt dokumentiert werden oder gar nicht? Wenn ja, wer darf sie sehen? Und wie haltet ihr es mit großen, roten Boxen, die davor warnen, sie zu benutzen? Bringt das alles nichts, weil sie ja doch benutzt werden egal wie stark gewarnt wird? Womit wir wieder bei der ersten Frage sind: Sollte man die Doku dazu lieber gar nicht schreiben oder zumindest nicht publizieren, um zu verhindern, dass Benutzer solche internen Funktionen oder Methoden aufrufen? Habt ihr vielleicht Erfahrung oder allgemeine Richtlinien, die ihr teilen könnt?

So, das waren meine Fragen. Ich kann keine von diesen sicher beantworten und bin gespannt, wie sich das hier entwicklen wird.

@derdon: Man dokumentiert ja nicht nur für die (End)Nutzer von Bibliotheken, sondern auch für sich selbst. Eine Bibliothek zu warten, die man vielleicht ein oder zwei Jahre nicht mehr angefasst hat, und wo keine der nicht-öffentlichen Funktionen/Methoden in irgend einer Weise dokumentiert sind, wird lustig. Ich dokumentiere so etwas genau wie alles andere. Wenn man keine Java-API-Doku-ähnliche Dokumentation generiert, sondern beispielsweise Sphinx benutzt, hat man ja auch ganz gut unter Kontrolle was davon in der Dokumentation für Bibliotheksbenutzer landet.

Das Thema scheint wohl doch nicht so kontrovers zu sein wie ich dachte. Dann fasse ich einfach zusammen, was BlackJack gesagt hat: alles dokumentieren, interne Details intern lassen, d.h. nur fuer Entwickler des Projekts zugaenglich machen.

Alles publizieren, sowohl Code als auch Doku unter eine freie Lizenz stellen und zusehen was passiert

Alles dokumentieren, sehe ich auch so. Wer schon mal nach einem halben Jahr vor der Frage stand "was habe ich mir damals dabei gedacht", der weiß warum...