Wenn erwartet wird, dass ein Argument für eine Funktion eine bestimmte (oder äquivalente) Struktur ist, die mit list , tuple und dict von python, wie und wo
Ein Beispiel Dokumentation :
%Vor%Ein bisschen umständlich; einige Probleme:
edit: Das Beispiel ist nicht , wenn versucht wird, Typen zu erzwingen, sondern eine Struktur zu dokumentieren. Für den Punkt ist duck typing ok .
Meine einfache Antwort auf Ihre Frage ist, das Zen von Python zu zitieren: " Explizit ist besser als implizit ". In Bezug auf Ihre Frage bedeutet dies, genau auszuschreiben, was benötigt wird, auch wenn es einen ganzen Absatz braucht, um ein einzelnes Argument zu dokumentieren. Lies einfach die Python-Dokumente, um Beispiele zu sehen. In Ihrem speziellen Fall können Sie die Duck-Typisierung angeben, indem Sie auf eine Sequenz und nicht auf ein Tupel verweisen (siehe Ссылка ).
Wenn Sie Python 3 verwenden, könnten Sie an "function annotations" interessiert sein. Sie sind nicht erzwungen und völlig optional, scheinen aber zu tun, was Sie wollen. Eine Annotation kann ein beliebiger Python-Ausdruck sein und sie sind neben den Argumenten im Funktionskopf enthalten. Zum Beispiel (tut mir leid, es ist ein bisschen unsinnig):
%Vor%Weitere Details (einschließlich möglicher Anwendungsfälle und Beispiele) finden Sie hier: PEP 3107
Ich habe vor einiger Zeit in meiner Arbeit auf dieses Problem gestoßen. Basierend auf meinen persönlichen Recherchen (zB einer gründlichen Google-Suche) gibt es keinen Standard für die Dokumentation komplexer, geschachtelter Funktionsargumente. Ich erfand schließlich meinen Ansatz, der <> verwendet, um Elemente der Datenstruktur zu bezeichnen, und jedes Element erhält einen eigenen Header und einen eigenen Absatz in den Dokumenten. Zum Beispiel:
Diese Dokumentation könnte in den Doc-Strings für die Funktion enthalten sein, aber in meinem Fall habe ich mich entschieden, sie in ein separates Dokument aufzuteilen. Der Ansatz kann auf kompliziertere Strukturen erweitert werden. Siehe zum Beispiel meine Dokumentation hier .
Ich denke, meine unbeliebteste Funktion hat jemals wirklich gute Inline-Dokumente.
Schauen Sie sich die validate docs hier an:
Die umfassendste Docstring-Spezifikation, die ich gesehen habe, ist der NumPy Docstring Style Guide
Tags und Links python data-structures documentation docstring