Клуб API Карт

Клуб API Карт

Документация

Пост в архиве.

Осталось очень странное ощущение от документации, непонятно для кого его писали, теоретическая часть отделена от примеров, вместо группировки по возможностям (описание краткое, примеры, подробное описание методов) информация фрагментирована (описание в одном месте, пример в другом, подробного описания вообще не дождаться)

Возмем даже простейшую установку точек на карте. Что нужно показать? Как поставить точку зная координаты, как поставить точку зная адрес, как поставить сразу много точек, как сделать чтобы много точек не вешали браузер. Вместо понятных ответов на эти вопросы есть общее описание того, что такое точка, описание групп объектов, геокодинга, совершенно невнятное описание "активных областей", в разных разделов без какой-либо вменяемой провязки. Примеры в виде куска html с комментариями в коде это вообще позорище. 

20 комментариев
Авторизуйтесь, чтобы оставить комментарий
KDV
28 января 2016, 06:40
В отношение описания Активных областей присоединяюсь, понять используемую технологию просто невозможно по случайно выдернутым фрагментам кода. Куда полезнее было бы опубликовать 2-3 полных исходника работающих примеров с развернутыми комментариями как это сделано в более ранних разделах документации.
rodlex
28 января 2016, 06:40
Примеры есть:
http://api.yandex.ru/maps/jsapi/doc/mod/tasks/how-to-use-hotspots-overlays.xml
http://api.yandex.ru/maps/jsapi/doc/mod/tasks/how-to-create-hotspots-layer.xml

Мы работаем над рефакторингом документации. Описание модулей это тоже затронет ;)

Спасибо за ваше сообщение.
KDV
28 января 2016, 06:40
Повторюсь немного, к документации в целом у меня никаких нареканий нет. Все очень хорошо и детально расписано, но вот Активные области как то "жиденько" чтоли ;)
rodlex
28 января 2016, 06:40
Перепишем %)
rodlex
28 января 2016, 06:40
Точки на карте - это метки. Вы можете пойти в руководство разработчика или сразу на страницу примеров.

Если вам нужно узнать координаты по адресу, то вам нужно выбрать геокодер в разделе документации Поиск по карте. Или опять же посмотреть примеры, как по js-геокодеру, так и по http-геокодеру.

Вы правы, с модулями у нас не очень хорошие провязки в руководстве. Мы постоянно работаем на улучшением нашей документации, ваши пожелания будут обязательно учтены. Спасибо за фидбек.

А почему вы считаете, что примеры в виде фрагментов html с комментариями выглядят неподобающим образом?
ikenovodvorsky
28 января 2016, 06:40
Хотелось бы примеры в виде туториалов от простого к сложному

Как добавить точку на карту? Как добавить много точек на карту? Как привязать к точке событие? Как добавить точки из YMapsML -- примерно в таком порядке описывать разные возможности с комментариями, а не просто кодом. Я разберусь, но в целом хотелось бы видеть цельную и простую документацию.
rodlex
28 января 2016, 06:40
Мы обязательно учтем ваше замечания. Спасибо.

Еще один вопрос. А где описано просто кодом без комментариев? В руководстве или справочнике?
vaddoo
28 января 2016, 06:40
Айк, спасибо за дельные комментарии. Мы как раз думаем над некоторыми изменениями на промо-сайте, учтем ваши пожелания. А если остались какие-то нерешенные вопросы, задайте их здесь, в клубе, в прямой форме, вам обязательно помогут.
Andrey.Cjkjvfnby
28 января 2016, 06:40
Мне не нравится разрозненное описание стилей и настроек.  Хотелось бы видеть пример в котором будет указанны все возможные стили и опции (в режиме по умолчанию) для объекта (метка, линия, ....)

что то похожее на:

var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37, 55), {draggable: 1,
    hintOptions: {
        maxWidth: 100,
        showTimeout: 200,
        offset: new YMaps.Point(5, 5)
    },
    balloonOptions: {
        maxWidth: 70,
        hasCloseButton: false,
        mapAutoPan: 0
    }
});

Только полное.


Со страницы  с описание метки не очевидно где живут ее стили.

И далее по метке

Мне вначале было очень непривычно работать в документации с наследуемыми методами.
Они написанны мелким шрифтом. А когда по странице ищеш текстовым поиском по типу возвращаемых данных, то они не ищутся (попробуйти найти методы которые работают с тем же YMaps.Style)
Я за то чтобы информацию о наследуемых методах отображать точно так же как и о родных. (далеко не всем нужны эти YMaps.I*** интерфейсы)



В кратком и подробном описании функций:
YMaps.Placemark(coordPoint, options) 
поменять на
YMaps.Placemark(coordPoint, options) 

В подробном описании конструктора поменять местами параметры и пример.


Можно в начало описания добавить ссылку на примеры (См.: Метка, Примеры)


rodlex
28 января 2016, 06:40
Спасибо за ценные замечания. Будем улучшать)
Andrey.Cjkjvfnby
28 января 2016, 06:40
Справочник по программному интерфейсу не содержит упоминание:
YMaps.jQuery
Туда стоит добавить упоминание, номер версии, отличия от базовой версии и ссылочку на документацию.

rodlex
28 января 2016, 06:40
http://api.yandex.ru/maps/jsapi/doc/ref/reference/ymaps.xml#jQuery
Andrey.Cjkjvfnby
28 января 2016, 06:40

Сорри, смутила большая буква почти в начале слова.

depp
28 января 2016, 06:40

полностью согласен. работаю веб-разработчиком црм систем много лет. помню надо было в гугл карты вывести 200 объектов с адресами на сайт и при нажатии на точку отобразить информацию об объекте, которая загружалась аяксом - я не помню чтобы долго возился. сервис получился быстрым и безпроблемным. и вообще раньше все делал на гугл.картах. сейчас же задача стоит вывести все на яндекс. это просто что-то с чем-то. везде абсолютно разные решения. хотя задача та же самая что я описал выше. есть список адресов, необходимо определить координаты (это все что я успел сделать за ночь по документации яндекса), затем нанести точк на карту, и при нажатии на точку показывать информацию по ней (неважно через аякс либо загруженную сразу). я прочитал почти документацию и не имею представления как это сделать. по любой шкале оценок яндекс картам ноль за это. сами разработчики карт хоть понимают что их система из-за этого выглядит не приглядно... у меня только одно слово сейчас на уме. из пяти букв. первая г.

dimik
28 января 2016, 06:40

Обычно комментарии в стиле "все говно" мало полезны.

Лучше рассказать где вы искали, что вы читали, и почему не нашли ответ

depp
28 января 2016, 06:40

все искал здесь: http://api.yandex.ru/maps/doc/jsapi/

описанная мною несложная задача заняла всю ночь по времени разработки. это очень долго при том что я описал.

ответ "как" я уже нашел. к сожалению увидя перед собой решение на node.js я сразу же отклонил его по причине того, что врядли заказчик выберет себе хостинг, где ему позволят запустить его. но кто же знал что в нем таится маленькая ссылка с нелогичным описанием:

Для формирования и отправки запроса геокодеру используется функция geocode. Она принимает на вход следующие параметры:

...

Кто бы мог подумать что за этой ссылкой скрывается описание запроса к сервису чтобы получить координаты по нужным адресам не только с помощью node.js? я использую чистый php. чтобы написать функцию из трех строк для получения координат был потрачен не один час в поисках как это сделать.

Дальше нам надо разместить все точки на карте, но при этом сделать так чтобы было все быстро и было описание каждой точки с нужным мне оформлением. Где это в документации в одном месте? где описание как добавлять в GeoObjectCollection массив данных со своими координатами и описанием точек (оформление балуна) в одном месте?

Типичная задача у меня была.

Дальше предстоит задача опять с яндекс картами - это добавление метки по клику и задание ей определенных параметров с последующим сохранением описания и координат в базу. Я даже не знаю где это может быть в документации.

добавлю также, что при прямом геокодировании возвращаются координаты - "долгота широта", когда везде в сервисе используются "широта, долгота", что по моему не совсем логично.

dimik
28 января 2016, 06:40

Вы можете прогеокодировать весь список координат на своей машине с помощью node.js модуля и залить их в базу хостинга. Вы можете потратить полчаса и переписать этот модуль на другой языковой стек если вам так удобно

 

Мы не можем сделать решения на все случаи жизни и удовлетворяющие всех пользователей и работающие на всех хостингах.

 

Непонятно почему ваши частные задачи должны быть в документации в одном месте. В документации описаны классы АПИ (откройте любую документацию - везде так)

 

Координаты в АПИ могут быть в любом порядке - это регламентируется параметром coordorder

 

depp
28 января 2016, 06:40

да понятно что апи, но слишком уж путанная документация. возможно не упомянул, но стоит задача - дать возможность пользователю добавлять новые адреса с поледующим определением координат уже после сдачи проекта. но это уже сделано, с этим вопросов нет.

сам сервис содержит в себе огромный потенциал для разработчиков, но из-за такой документации не каждый будет его использовать.

и уж в GeoObjectCollection могло быть достойное описание того что я описал, так как метод как раз под мою задачу. в чистом виде практически.

 

и кто вообще придумал в документации писать что параметры этого метода соответствуют этому и вы можете посмотреть их там, вместо того чтобы описать все одном месте.

я не ругаю само апи. оно возможно и прекрасно составлено. но вот где бы прочитать как нормально этим пользоваться - еще одна задача помимо самой разработки на этом апи.

dimik
28 января 2016, 06:40

Документация - описана в стандартном синтаксисе jsdoc, и в принципе мало чем отличается от других документаций.

Можете привести пример документации,

где все в одном месте и которой вам удобно пользоваться?

 

depp
28 января 2016, 06:40

php.net, api.jquery.com, getbootstrap.com