Как задокументировать пользовательскую библиотеку в Arduino

Question

Как задокументировать пользовательскую библиотеку в Arduino

library documentation

Я создал свою собственную библиотеку, и она работает безупречно. Теперь я хочу добавить к нему некоторую документацию, которую сможет понять Arduino IDE.

Для функций из самой среды разработки Arduino, таких как delay(ms), вы можете щелкнуть их правой кнопкой мыши, а затем выбрать Найти в справочнике. Как я могу добавить эту функцию в свою библиотеку?

@LukasFun, 👍4

Обсуждение

Я не отвечаю на ваш вопрос, потому что мне также интересно узнать, возможно ли это вообще. Насколько я знаю, REFERENCE_LINK является ссылкой на собственный основной справочник Arduino. Libs может иметь только дополнительную папку для размещения в ней документов, но IDE полностью игнорирует это., @Peter Paul Kiefer

2 ответа

Лучший ответ:

▲ 2

Arduino использует файл keyword.txt для выделения слов. и определить страницу ссылки на ключевые слова. Но справочная страница должна находиться в папке reference установки IDE, а ключевое слово.txt содержит только имя файла, а не путь.

REFERENCE_LINK В этом поле указана страница справочника по языку Arduino, которую нужно открыть, щелкнув правой кнопкой мыши > Найти в справочнике или Справка > Найти в справочнике, когда курсор находится на этом ключевом слове. Как правило, не имеет смысла определять поле REFERENCE_LINK для ключевых слов сторонних библиотек, поскольку они вряд ли будут в справочнике по языку Arduino.

У меня есть библиотека, которая реализует WiFiClient и WiFiServer, как и библиотека Arduino WiFi, поэтому я могу связать файл keywords.txt со ссылкой на Arduino следующим образом:

WiFiClient  KEYWORD2    WiFiClient
WiFiServer  KEYWORD2    WiFiServer
WiFiUDP     KEYWORD2    WiFiUDPConstructor

Используемые имена являются именами файлов html в Arduino\reference\www.arduino.cc\en\Reference.

7 ноя 19, @Juraj

ответ в том, что это невозможно, @Juraj

я обновил ответ, @Juraj

ссылочные имена в keyword.txt — это имена html-файлов, расположенных где-то в ссылочной папке, @Juraj

ключевые слова.txt должны использовать вкладки для разделения полей. ты IDE перезапускал?, @Juraj

извините, файл должен находиться в C:\Program Files (x86)\Arduino\reference\www.arduino.cc\en\Reference, @Juraj

у вас есть файл keywords.txt в папке библиотеки рядом с library.properties? соответствует ли ваша библиотека спецификации библиотеки 1.5?, @Juraj

здесь это работает. как только я помещаю третье поле в keyword.txt, «Найти в ссылке» включается, даже если имя файла недействительно. Теперь я вижу, что текстовый курсор тоже должен стоять на слове., @Juraj

библиотека WiFiEspAT (в менеджере библиотек), но я опубликовал ее без keywords.txt. Чтобы проверить этот ответ, я скопировал keywords.txt из библиотеки Arduino WiFi и добавил строку для beginAP, которой нет в библиотеке Arduino WiFi. и я добавил справочный файл в папку Reference, @Juraj

Эта библиотека работает. Что мне нужно сделать, чтобы моя собственная библиотека работала так? Не могли бы вы предоставить минимальный пример пользовательской библиотеки?, @LukasFun

https://github.com/jandrassy/lab/tree/master/Foo, @Juraj

Я только что узнал кое-что очень интересное. При написании ключевых слов из моей библиотеки в IDE просто сами по себе или в виде something.keyword они работают так, как задумано. Но если я пишу их в виде Library::keyword (как это делается со статическими вещами из библиотеки) ключевое слово подсвечивается, но функция найти его в справочнике уже не работает. Почему это и как это исправить?, @LukasFun

Я не могу изменить работу IDE, @Juraj

@*LukasFun* · Accepted Answer · 2019-11-13 17:30-00:00

Хорошо, пришло время дать мой самый исчерпывающий ответ на StackExchange (спасибо @Juraj за помощь в этом).

Чтобы продемонстрировать все шаги, необходимые для этого, в этом ответе будет использоваться пример библиотеки, которая будет называться Foo.

Начнем:

Чтобы добавить в свою библиотеку документацию, с которой может работать Arduino IDE, сначала необходимо поместить библиотеку в правильный каталог. Это либо папка library в папке sketchbook (вы можете найти ее, выбрав File>Preferences>Расположение Sketchbook, по умолчанию это

C:\Users\YourUsername\Documents\Arduino\libraries

или

InstallationDirectoryOfYourIDE\portable\sketchbook\libraries

если вы используете переносную установку) или в

InstallationDirectoryOfYourIDE\libraries

В какое из двух мест вы поместите свою библиотеку, зависит от вас, оба работают (кроме случаев, когда вы помещаете в оба места одновременно). Вы должны помнить об этом: если вы поместите свою библиотеку в папку libraries своего альбома, только у вас будет доступ к этой библиотеке. Если на том же ПК есть другие пользователи, которые смогут использовать вашу библиотеку, вы должны поместить ее в папку общих библиотек (если у вас нет доступа к этой папке, потому что она принадлежит другому пользователю, и вы не являетесь админ, тогда плохо, извини ;).

Ваша библиотека должна содержать как минимум файл Foo.h, который может находиться непосредственно в папке вашей библиотеки (старый стандарт) или в подпапке src в папка вашей библиотеки (актуальный стандарт). Содержимое файла для данного примера абсолютно произвольно (например, просто оставьте его пустым).

Дальше вам понадобится действительный файл library.properties для вашей библиотеки. Вы можете создать и отредактировать его с помощью любого текстового редактора, например блокнота. Этот файл нужно поместить прямо в папку библиотеки.

Вот минимальный пример для этого файла, который работает:

имя=Фу
версия=1.0.0
автор=Ваше имя
сопровождающий=Ваше имя
предложение=что-то
параграф=что угодно
url=http://example.com

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

Теперь мы можем указать, какие слова будет выделять IDE и какие из них должны ссылаться на какую справочную страницу (чтобы убедиться, что это работает в принципе, нет необходимости создавать собственные файлы .html). еще). Для этого создайте файл keywords.txt в папке вашей библиотеки. В нем вы пишете что-то вроде этого:

foo KEYWORD2    Foo

В этом примере foo — это ключевое слово, которое будет выделено в среде IDE (и при щелчке правой кнопкой мыши появится опция Найти в ссылке). KEYWORD2 указывает, как именно foo будет выделен (цвет, жирность и т. д.), в этом случае он будет выглядеть как обычный текст оранжевым цветом (еще раз, см. Спецификация библиотеки Arduino для более подробной информации). Foo — это имя файла .html (без расширения), который открывается, когда вы щелкаете правой кнопкой мыши foo в среде IDE и выбираете Найти в справочнике. Он должен находиться в этой папке:

InstallationDirectoryOfYourIDE\reference\www.arduino.cc\en\Reference

Эти три слова разделены настоящим табулятором (а не несколькими символами пробел). Перед созданием собственного файла .html вы можете просто скопировать туда один из файлов и переименовать его в Foo. Обратите внимание, что ваша библиотека не должна содержать ничего, кроме трех упомянутых файлов и некоторого файла в справочной папке, чтобы это работало. На этом этапе вам следует перезапустить IDE и проверить, выделено ли ключевое слово foo и предлагается ли опция Найти в справочнике при щелчке правой кнопкой мыши. Если да, то успехов! Теперь вы можете перейти к созданию собственного файла .html и поместить его в справочную папку.

Вы можете начать с простого изменения одного из существующих файлов, чтобы он соответствовал стилю API Arduino, но вы также можете создать свои собственные файлы. Однако, вероятно, лучший вариант — написать свою библиотеку в соответствии со стандартами doxygen, а затем позволить doxygen сделать всю работу за вас, создав файл автоматически.

Еще одно замечание: этот метод работает для любых ключевых слов, которые используются способом yourKeyword или something.yourKeyword, но не Something: :yourKeyword (именно так вы бы использовали статическую функцию или переменную в своей библиотеке). По словам @Juraj, это вызвано IDE. Однако есть обходной путь: заменить каждую строку в файле keywords.txt

.

yourKeyword KEYWORDX    ReferenceFile

с

yourKeyword KEYWORDX    ReferenceFile
YourLibrary::yourKeyword    KEYWORDX    ReferenceFile

Таким образом, yourKeyword будет выделен, как и следовало ожидать, но такие вхождения, как YourLibrary::yourKeyword, также вызовут опцию Найти в ссылке при щелчке правой кнопкой мыши.

На сегодня все. Спасибо и до свидания!