GoogleCodeExporter
commented
9 years ago Подробнее. Человек заходит на страницу. У
него два вопроса: зачем это и как это юзать.
И он хочет получить на первый ответ вопрос
сразу, а на второй - как можно проще и яснее.
Отсюда следует, что идеально в первом же
предложении сказать, что это за библиотека
("... - это библиотека, позволяющая
эффективно хранить координаты" или что там
еще). Подробности (для реинжиниринга,
почему она лучше существующих) - уже позже.
Теперь про то, как использовать. Поставьте
себя на место человека - что ему нужно? Для
практических целей ему нужно знать, что
именно хранят Ваши координаты (файл,
строку, столбец, смещение - и совершенно
плевать, в каком формате, и уж точно ему не
хочется вникать в те типы, которые Вы так
подробно описали). Что он умеет? У него уже
есть (ну, должно быть) понимание того, как
работет его лексер, и он понимает, что у
токена есть координаты, и он догадывается,
что его координаты переводимы в Ваши.
Остается вопрос - как их перевести. Тут
наиболее простой подход - пример. Причем
человеку хочется потратить минимум усилий
на разбирательство, поэтому идеальный
случай - пример построения лексера с
использованием библиотеки. Возможно, если
контекст большой, стоит сделать один
большой сторонний пример (в том числе и для
других целей), и здесь на него просто
сослаться (на часть "построение лексера",
например).
Теперь человек хочет достать координаты.
Тут тоже лучше пример сделать. Возможно,
еще лучше будет сделать сравнение с
реализацией без библиотеки, чтобы
пользователь легче понял различия.Original comment by dimo...@gmail.com on 1 Jul 2013 at 3:12
Original issue reported on code.google.com by
dimo...@gmail.comon 9 Jun 2013 at 3:15