[Erledigt] "Schnittstellen" Dokumentation

d0ne · 05.03.2010, 21:09

Hallo,

ich suche eine Möglichkeit eine "Schnittstelle", welche ich in PHP geschrieben habe ordentlich zu dokumentieren. Ich bin mir nicht sicher ob man dazu "Schnittstelle" sagen darf, im Grunde bekommen die Scripte per GET/POST verschiedene Parameter machen damit was und geben am Schluss ein Ergebnis zurück. Jetzt möchte ich das Dokumentiere á la "Script1 braucht die ID und das Passwort als Eingabe berechnet dir dann irgendwas und gibt dir am Ende deinen Namen zurück. Folgende Fehler können Auftreten ..." und das in Schön/standardisiert wie auch immer.

Gibt es da schöne, bzw. Standard-Möglichkeiten, "wie man das macht" ?

Ich hoffe ihr könnt mir helfen
mfg
d0ne

PS: Allgemein ich bin dabei meinen Code immer mehr mit PHPDoc Parameter/Dokumentation zu versehen. "Reicht denn das", wenn ich den Quellcode dokumentiere oder brauche ich "noch mehr" - wenn ja, was?

nikosch · 05.03.2010, 21:14

Allgemein würde man das wohl als API bezeichnen. Das I steht dabei für die Schnittstelle (Interface).

chorn · 05.03.2010, 21:37

Überleg dir doch einfach mal, was jemand, der deine Schnittstelle noch nicht kennt und diese benutzen möchte, braucht, um das Verhalten unter verschiedenen Bedingungen zu verstehen und anzuwenden. Und überleg dir, was du für Infos brauchst, wenn du die Schnittstelle mal ein Jahr lang nicht benutzt hast.

Was du noch dokumentieren musst hängt davon ab, wer das Script denn später mal lesen soll.
Und eine, zumindest für mich, vorbildliche Dokumentation ist die auf PHP.net. - klar strukturiert, Ein- und Ausgabe, Fehlerbehandlung, Beispiele - alles beschrieben.

Koala · 06.03.2010, 01:16

üblicherweise bietet man dem User ein Beispielscript zur Abfrage der API an
und fügt die (XML-)Struktur im Erfolgsfall und eine Liste der möglichen Fehlercodes bei.
Schau Dir mal verschiedene Schnittstellenbeschreibungen von SMS-Providern,
Banken etc. an.
Bei umfangreichen APIs wie bei Google, Paypal, ebay usw. gibts dann eben richtige Dokus
mit Beschreibung der Methoden, einem Anwenderforum etc.

d0ne · 08.03.2010, 07:43

Hallo,

so, ich hatte leider noch keine Zeit mich zu melden, deshalb erst jetzt!

Danke für die Antworten, ich denke für so ein "kleines Projekt" wie bei mir kann ich es machen wie ich will. Es geht mehr darum, "dass eine Dokumentation da ist" als das aktiv verschiedene Leute auf diese Angewiesen wären.
Ich denke ich werde mir mal angucken wie genau der Output von PHPDoc ist und dann mir ein "kleines Wiki" aufbauen. Dann habe ich wenig arbeite (außerhalb der eigentlichen Dokumentation) und es sieht gar nicht so schlecht aus!

mfg
d0ne

Themen-Optionen
Druckbare Version zeigen Jemanden per E-Mail auf dieses Thema hinweisen
Thema bewerten
Thema bewerten:

Ähnliche Themen
Thema	Autor	Forum	Antworten	Letzter Beitrag
[Erledigt] &amp;amp;amp;quot;DocType XHTML Strict&amp;amp;amp;quot; (Dokumentation?)	Patrick Schwarz	HTML, Usability und Barrierefreiheit	4	04.09.2009 21:00
FPDF : Dokumentation oder kleines Beispiel gesucht	SvenLittkowski	PHP Tipps 2006	5	01.11.2006 02:26
php_svn - Dokumentation?	freq.9	PHP Tipps 2006	2	27.06.2006 20:12
Platz halter Dokumentation?	b++	PHP Tipps 2006	5	20.03.2006 08:33
Dokumentation von Code	ChewyF5	PHP-Fortgeschrittene	7	09.08.2005 14:28
&quot;DocType XHTML Strict&quot; (Dokumentation?)	Patrick Schwarz	HTML, Usability und Barrierefreiheit	0	05.08.2005 10:56
DocType XHTML Strict (Dokumentation?)	Patrick Schwarz	HTML, Usability und Barrierefreiheit	0	05.08.2005 10:25
[Erledigt] DocType XHTML Strict (Dokumentation?)	Patrick Schwarz	HTML, Usability und Barrierefreiheit	0	05.08.2005 10:24
link zu dokumentation von ezpdf		Beitragsarchiv	3	13.07.2005 12:24
Dokumentation Datentypen PHPMyAdmin	Lia	PHP Tipps 2005	3	14.04.2005 15:02
[Erledigt] PHP Dokumentation für seine eigene Seite generieren?		PHP-Fortgeschrittene	4	02.04.2005 07:56
Dokumentation GDLIB in Deutsch		PHP Tipps 2004-2	2	19.11.2004 16:45
Suche Dokumentation ?		PHP Tipps 2004	2	25.10.2004 09:38
Dokumentation von Klassen-Methoden	brain_overload	PHP-Fortgeschrittene	3	07.10.2004 14:08
Dokumentation von PHP-Code	inu	PHP Tipps 2004	4	02.09.2004 13:28

05.03.2010, 21:09
d0ne Benutzer Registriert seit: 21.02.2010 Beiträge: 70 PHP-Kenntnisse: Fortgeschritten	[Erledigt] "Schnittstellen" Dokumentation Hallo, ich suche eine Möglichkeit eine "Schnittstelle", welche ich in PHP geschrieben habe ordentlich zu dokumentieren. Ich bin mir nicht sicher ob man dazu "Schnittstelle" sagen darf, im Grunde bekommen die Scripte per GET/POST verschiedene Parameter machen damit was und geben am Schluss ein Ergebnis zurück. Jetzt möchte ich das Dokumentiere á la "Script1 braucht die ID und das Passwort als Eingabe berechnet dir dann irgendwas und gibt dir am Ende deinen Namen zurück. Folgende Fehler können Auftreten ..." und das in Schön/standardisiert wie auch immer. Gibt es da schöne, bzw. Standard-Möglichkeiten, "wie man das macht" ? Ich hoffe ihr könnt mir helfen mfg d0ne PS: Allgemein ich bin dabei meinen Code immer mehr mit PHPDoc Parameter/Dokumentation zu versehen. "Reicht denn das", wenn ich den Quellcode dokumentiere oder brauche ich "noch mehr" - wenn ja, was?


Mister Ad PHP Code Flüsterer Registriert seit: 21.08.2005 Beiträge: 4682 PHP-Kenntnisse: Fortgeschritten

05.03.2010, 21:14
nikosch moderatives Dielektrikum Registriert seit: 21.05.2008 Beiträge: 34.256 PHP-Kenntnisse: Fortgeschritten	Allgemein würde man das wohl als API bezeichnen. Das I steht dabei für die Schnittstelle (Interface). __________________ -- One pixel is still too big. Please make it smaller. ASAP. Initiative Mittelstand. Die wichtigste Gestaltungsregel im Screendesign ist Pi mal Daumen des Arbeitgebers. --

05.03.2010, 21:37
chorn Erfahrener Benutzer Registriert seit: 07.12.2009 Beiträge: 814 PHP-Kenntnisse: Fortgeschritten	Überleg dir doch einfach mal, was jemand, der deine Schnittstelle noch nicht kennt und diese benutzen möchte, braucht, um das Verhalten unter verschiedenen Bedingungen zu verstehen und anzuwenden. Und überleg dir, was du für Infos brauchst, wenn du die Schnittstelle mal ein Jahr lang nicht benutzt hast. Was du noch dokumentieren musst hängt davon ab, wer das Script denn später mal lesen soll. Und eine, zumindest für mich, vorbildliche Dokumentation ist die auf PHP.net. - klar strukturiert, Ein- und Ausgabe, Fehlerbehandlung, Beispiele - alles beschrieben. Geändert von chorn (05.03.2010 um 21:42 Uhr).

06.03.2010, 01:16
Koala Erfahrener Benutzer Registriert seit: 28.09.2008 Beiträge: 1.127 PHP-Kenntnisse: Fortgeschritten	üblicherweise bietet man dem User ein Beispielscript zur Abfrage der API an und fügt die (XML-)Struktur im Erfolgsfall und eine Liste der möglichen Fehlercodes bei. Schau Dir mal verschiedene Schnittstellenbeschreibungen von SMS-Providern, Banken etc. an. Bei umfangreichen APIs wie bei Google, Paypal, ebay usw. gibts dann eben richtige Dokus mit Beschreibung der Methoden, einem Anwenderforum etc.

08.03.2010, 07:43
d0ne Benutzer Registriert seit: 21.02.2010 Beiträge: 70 PHP-Kenntnisse: Fortgeschritten	Hallo, so, ich hatte leider noch keine Zeit mich zu melden, deshalb erst jetzt! Danke für die Antworten, ich denke für so ein "kleines Projekt" wie bei mir kann ich es machen wie ich will. Es geht mehr darum, "dass eine Dokumentation da ist" als das aktiv verschiedene Leute auf diese Angewiesen wären. Ich denke ich werde mir mal angucken wie genau der Output von PHPDoc ist und dann mir ein "kleines Wiki" aufbauen. Dann habe ich wenig arbeite (außerhalb der eigentlichen Dokumentation) und es sieht gar nicht so schlecht aus! mfg d0ne