OpenLayers API-Dokumentation vs. Entwicklerdokumentation

10

Die OpenLayers-Website enthält zwei Referenzdokumentationen:

Für die meisten Klassen enthalten die API-Dokumente eine kleine Teilmenge der Entwicklerdokumentation. Ich stelle fest, dass ich normalerweise nicht viel erreichen kann, wenn ich nur die in den API-Dokumenten beschriebenen Funktionen verwende. Daher verwende ich die Entwicklerdokumentation (und lese die Quelle und die Beispiele).

Was ist der offizielle Unterschied zwischen diesen beiden Dokumentationssätzen? Beschreiben die API-Dokumente Schnittstellen, von denen erwartet wird, dass sie stabil sind? Riskiere ich zukünftige Schäden, wenn ich Funktionen verwende, die nur in der Entwicklerdokumentation beschrieben sind?

Kristopher Johnson
quelle

Antworten:

3

Ich muss meine Antwort bearbeiten, um ein wenig zu korrigieren. In Bezug auf OpenLayers gibt es mehrere Hauptdokumentationen:

1 - Ein Wiki wie eines

2 - API-Dokumentation

3 - Entwicklerdokumentation

4 - Dokumentation zur letzten Version / Trunk-API

5 - Letzte Version / Trunk Entwicklerdokumentation

Die API-Dokumentation soll die stabilen Details der API beschreiben , während die Entwicklerdokumentation auf andere Details verweist, die bei der Entwicklung von OpenLayers-Anwendungen erforderlich sind.

"Es gibt zwei Arten von Eigenschaften / Methoden im OpenLayers-Code: Ein Satz ist der Satz von API-Methoden und -Eigenschaften. Es gibt auch zusätzliche interne Eigenschaften, die nicht für die API verfügbar sind. Javascript hat keine privaten Mitglieder, daher gibt es keine Technische Einschränkung für die Verwendung dieser nicht dokumentierten Methoden im Anwendungscode. Obwohl wir alle Anstrengungen unternehmen, um APIs zwischen Releases nicht zu ändern, können sich Methoden und Eigenschaften, die nicht explizit als API-Methoden deklariert sind, in kleineren Releases ändern.

Die obige Dokumentation "(das API-Dokument 2 und 4)" enthält nur die API-Methoden. Die vollständige Dokumentation für Entwickler / interne Bibliotheken finden Sie auch unter "(3 und 5)". Es kann jedoch nicht davon ausgegangen werden, dass Methoden, die in der obigen API-Dokumentation nicht verfügbar sind, zwischen den Versionen gleich bleiben. Wenn Sie die in diesen Dokumenten enthaltenen Methoden verwenden, müssen Sie möglicherweise Änderungen an Ihrem Anwendungscode vornehmen, um zwischen kleineren Versionen von OpenLayers ausgeführt zu werden. "

GUTE ANTWORT: Sie sollten sich auf die API-Dokumente der neuesten Version (Link ab Punkt 2) verlassen, um sicherzustellen, dass Ihr Code gegenüber den neuen Versionen relativ sicher ist.

FALSCHE ANTWORT <>

Meine tatsächliche richtige Antwort basiert auf . Es gibt eine ähnliche Diskussion hier .

Niculita Mihai
quelle