Pascal Docs

Любые обсуждения, не нарушающие правил форума.

Модератор: Модераторы

Pascal Docs

Сообщение Prizzrak » 19.12.2018 01:45:11

В php есть такая штука как php docs. В php скриптах можно делать комментарии специального формата и тогда большинство современных сред разработки будут показывая подсказки показывать ещё и эти вот специальные комментарии. Вот пример:

Код: Выделить всё
      /**
       * Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       * @param int $objectId идентификатор сущности
       * @param bool|string $type тип сущности
       * @return bool|string
       */
      public function getObjectEditLink($objectId, $type = false) {
          ...
      }


Штука очень удобная. Есть ли что-то подобное в Lazarus?
Prizzrak
новенький
 
Сообщения: 70
Зарегистрирован: 01.10.2018 22:20:48
Откуда: Москва

Re: Pascal Docs

Сообщение sign » 19.12.2018 07:01:59

Код: Выделить всё
     { Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       @param int $objectId идентификатор сущности
       @param bool|string $type тип сущности
       @return bool|string }
      function getObjectEditLink(ObjectId: Integer; aType: string): string;


или

Код: Выделить всё
   
       // Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       // @param int $objectId идентификатор сущности
       // @param bool|string $type тип сущности
       // @return bool|string
      function getObjectEditLink(ObjectId: Integer; aType: string): string;
sign
энтузиаст
 
Сообщения: 1131
Зарегистрирован: 30.08.2009 09:20:53

Re: Pascal Docs

Сообщение alexs » 19.12.2018 09:21:45

а ещё есть fpdoc - вообще удобно писать документацию на исходники. При этом не замусориваеются сами исходники.
Аватара пользователя
alexs
долгожитель
 
Сообщения: 4053
Зарегистрирован: 15.05.2005 23:17:07
Откуда: г.Ставрополь

Re: Pascal Docs

Сообщение Prizzrak » 19.12.2018 19:08:29

sign писал(а):
Код: Выделить всё
     { Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       @param int $objectId идентификатор сущности
       @param bool|string $type тип сущности
       @return bool|string }
      function getObjectEditLink(ObjectId: Integer; aType: string): string;


или

Код: Выделить всё
   
       // Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       // @param int $objectId идентификатор сущности
       // @param bool|string $type тип сущности
       // @return bool|string
      function getObjectEditLink(ObjectId: Integer; aType: string): string;

И это будет работать? То есть в подсказках будет вылезать?

Добавлено спустя 3 минуты 5 секунд:
alexs писал(а):а ещё есть fpdoc - вообще удобно писать документацию на исходники. При этом не замусориваеются сами исходники.

То, что подсказки замусаривают исходники - это весьма спорное утверждение. С самых малых лет нас всех учили, что код надо комментировать. И действительно код с комментариями куда понятнее, чем без. Про fpdoc я почитал, правда уже после создания темы, Мне кажется, он не является заменой комментариев в коде. Хотя согласен, что вполне способен заменить функционал документриования в коде. Но как по мне, так зачем документацию писать отдельно, если комментарии в коде всё равно нужны.
Prizzrak
новенький
 
Сообщения: 70
Зарегистрирован: 01.10.2018 22:20:48
Откуда: Москва

Re: Pascal Docs

Сообщение Лекс Айрин » 19.12.2018 19:16:12

Prizzrak писал(а): Но как по мне, так зачем документацию писать отдельно, если комментарии в коде всё равно нужны.


Комментарии это все же заметки для программиста (или команды) пишущего код, чтобы не забыть какие-то особенности и нюансы, а документация это описание стандартного поведения кода позволяющее понять его, не залезая внутрь реализации.
Аватара пользователя
Лекс Айрин
долгожитель
 
Сообщения: 5723
Зарегистрирован: 19.02.2013 16:54:51
Откуда: Волгоград

Re: Pascal Docs

Сообщение sign » 20.12.2018 06:30:12

Prizzrak писал(а):И это будет работать? То есть в подсказках будет вылезать?

Да, это работает.
sign
энтузиаст
 
Сообщения: 1131
Зарегистрирован: 30.08.2009 09:20:53

Re: Pascal Docs

Сообщение zoltanleo » 20.12.2018 11:36:30

Prizzrak писал(а):Штука очень удобная. Есть ли что-то подобное в Lazarus?

Про комментирование кода и многое другое
Аватара пользователя
zoltanleo
постоялец
 
Сообщения: 457
Зарегистрирован: 17.10.2013 10:55:01

Re: Pascal Docs

Сообщение alexs » 20.12.2018 17:13:38

Prizzrak писал(а):То, что подсказки замусаривают исходники - это весьма спорное утверждение.

Краткое пояснение к тому, почему так сделано - необходимо.
Описание на 20 строк работы метода или куска кода - это уже мусор.
В качестве плохого примера - можно глянуть исходники UIB - строка кода-стока комментария. Код тяжело воспринимать.
Аватара пользователя
alexs
долгожитель
 
Сообщения: 4053
Зарегистрирован: 15.05.2005 23:17:07
Откуда: г.Ставрополь

Re: Pascal Docs

Сообщение serbod » 20.12.2018 18:40:17

alexs писал(а):Краткое пояснение к тому, почему так сделано - необходимо.
Описание на 20 строк работы метода или куска кода - это уже мусор.

Вот бы оно еще было удобным в использовании.. А то исходник отдельно, дока отдельно в нечитабельном виде.

Лучше научить IDE скрывать/показывать комменты определенного формата по одной кнопке. И чтобы ссылки в комментах работали, можно было сразу в браузере открыть страницу с подробной документацией с примерами.

Добавлено спустя 4 минуты 13 секунд:
Даже в том виде, как сейчас есть возможность по Shift-F1 вызывать браузер справки и передавать в него искомое слово вместе с контекстом. Я могу доработать браузер, добавить редактор. Но сам вызов справки не всегда работает.
Аватара пользователя
serbod
постоялец
 
Сообщения: 449
Зарегистрирован: 16.09.2016 11:03:02
Откуда: Минск

Re: Pascal Docs

Сообщение Prizzrak » 20.12.2018 21:33:29

zoltanleo писал(а):
Prizzrak писал(а):Штука очень удобная. Есть ли что-то подобное в Lazarus?

Про комментирование кода и многое другое

Спасибо!
Prizzrak
новенький
 
Сообщения: 70
Зарегистрирован: 01.10.2018 22:20:48
Откуда: Москва

Re: Pascal Docs

Сообщение alexs » 21.12.2018 11:48:31

serbod писал(а):учше научить IDE скрывать/показывать комменты определенного формата по одной кнопке

Просто наводишь мышку - в хинте будет
либо сделай отображение панели fpdoc - она тоже динамически отображает подсказку к элементу
У вас нет необходимых прав для просмотра вложений в этом сообщении.
Аватара пользователя
alexs
долгожитель
 
Сообщения: 4053
Зарегистрирован: 15.05.2005 23:17:07
Откуда: г.Ставрополь

Re: Pascal Docs

Сообщение serbod » 23.12.2018 12:39:56

Я говорю о скрытии "документальных" комментов, как это сделано во многих IDE для Java. В файле исходника они есть, а в IDE они скрыты, но можно и показать.
Аватара пользователя
serbod
постоялец
 
Сообщения: 449
Зарегистрирован: 16.09.2016 11:03:02
Откуда: Минск

Re: Pascal Docs

Сообщение zoltanleo » 23.12.2018 14:37:20

serbod писал(а):Я говорю о скрытии "документальных" комментов, как это сделано во многих IDE для Java. В файле исходника они есть, а в IDE они скрыты, но можно и показать.

А так?
Аватара пользователя
zoltanleo
постоялец
 
Сообщения: 457
Зарегистрирован: 17.10.2013 10:55:01

Re: Pascal Docs

Сообщение iN0k » 24.12.2018 12:55:47

давно как-то баловался ...
viewtopic.php?f=5&t=9979&p=82752&hilit=comment#p82752

но тему заглохла ... (((
iN0k
постоялец
 
Сообщения: 146
Зарегистрирован: 18.07.2012 14:09:50

Re: Pascal Docs

Сообщение zoltanleo » 24.12.2018 13:59:13

iN0k писал(а):но тему заглохла ... (((

Так ты выложи на англоязычном сайте в виде компонента-плагина, возможно кто-то возьмется допилить. Тут 1,5 человека в неделю ходят - конечно все заглохнет.
Аватара пользователя
zoltanleo
постоялец
 
Сообщения: 457
Зарегистрирован: 17.10.2013 10:55:01

След.

Вернуться в Потрепаться

Кто сейчас на конференции

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 14

Рейтинг@Mail.ru