Dokumentacja API OpenLayers vs. Dokumentacja programisty

10

Witryna OpenLayers zawiera dwa zestawy dokumentacji referencyjnej:

W przypadku większości klas Dokumenty API zawierają niewielki podzbiór tego, co jest w Dokumentacji programisty. Uważam, że zwykle nie mogę wiele zrobić za pomocą funkcji opisanych w Dokumentach API, dlatego korzystam z Dokumentacji programisty (i czytam źródło i przykłady).

Jaka jest oficjalna różnica między tymi dwoma zestawami dokumentacji? Czy Dokumenty API opisują interfejsy, które powinny być stabilne? Czy ryzykuję przyszłe uszkodzenie, jeśli użyję funkcji opisanych tylko w dokumentacji dla programistów?

Kristopher Johnson
źródło

Odpowiedzi:

3

Muszę edytować swoją odpowiedź, aby trochę poprawić. Powiązane z OpenLayers istnieje kilka głównych dokumentacji:

1 - Wiki typu wiki

2 - Dokumentacja API

3 - Dokumentacja programisty

4 - Dokumentacja API ostatniej wersji / trunk

5 - Ostatnia wersja / dokumentacja programisty trunk

Dokumentacja API ma na celu opisanie stabilnych szczegółów API , podczas gdy dokumentacja dla programistów wskazuje inne szczegóły, które są potrzebne przy tworzeniu aplikacji OpenLayers.

„W kodzie OpenLayers istnieją dwa rodzaje właściwości / metod: jeden zestaw to zestaw metod i właściwości API. Istnieją również dodatkowe właściwości wewnętrzne, które nie są narażone na działanie interfejsu API. JavaScript nie ma prywatnych członków, więc nie ma techniczne ograniczenie do używania tych nieudokumentowanych metod w kodzie aplikacji, ale chociaż dokładamy wszelkich starań, aby nie zmieniać interfejsów API między wydaniami, metody i właściwości, które nie są wyraźnie zadeklarowane jako metody API, mogą ulec zmianie w mniejszych wydaniach.

Dokumentacja powyżej „(dokument API 2 i 4)” obejmuje tylko metody API. Pełna dokumentacja programisty / biblioteki wewnętrznej jest również dostępna poniżej „(3 i 5)”, ale nie można polegać na metodach, które nie są dostępne w powyższej dokumentacji API powyżej. Jeśli korzystasz z metod zawartych w tych dokumentach, być może będziesz musiał wprowadzić zmiany w kodzie aplikacji, aby działały między mniejszymi wydaniami OpenLayers. ”

DOBRA ODPOWIEDŹ: Powinieneś polegać na dokumentach API najnowszej wersji, link z punktu 2, aby upewnić się, że twój kod jest względnie bezpieczny w stosunku do nowych wersji.

ŹLE ODPOWIEDŹ <>

Moja właściwa poprawna odpowiedź jest oparta na . Podobna dyskusja tutaj .

Niculita Mihai
źródło