Pascal Docs

[Prizzrak]

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

Код: Выделить всё

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

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

[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;


[alexs]

а ещё есть fpdoc - вообще удобно писать документацию на исходники. При этом не замусориваеются сами исходники.

[Prizzrak]

Код: Выделить всё

     { Возвращает ссылку на страницу, где можно отредактировать сущность модуля
       @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 секунд:

а ещё есть fpdoc - вообще удобно писать документацию на исходники. При этом не замусориваеются сами исходники.

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

[Лекс Айрин]

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

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

[sign]

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

Да, это работает.

[zoltanleo]

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

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

[alexs]

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

Краткое пояснение к тому, почему так сделано - необходимо.
Описание на 20 строк работы метода или куска кода - это уже мусор.
В качестве плохого примера - можно глянуть исходники UIB - строка кода-стока комментария. Код тяжело воспринимать.

[serbod]

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

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

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

Добавлено спустя 4 минуты 13 секунд:
Даже в том виде, как сейчас есть возможность по Shift-F1 вызывать браузер справки и передавать в него искомое слово вместе с контекстом. Я могу доработать браузер, добавить редактор. Но сам вызов справки не всегда работает.

[Prizzrak]

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

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

Спасибо!

[alexs]

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

Просто наводишь мышку - в хинте будет
либо сделай отображение панели fpdoc - она тоже динамически отображает подсказку к элементу

[serbod]

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

[zoltanleo]

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

А так?

[iN0k]

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

но тему заглохла ... (((

[zoltanleo]

но тему заглохла ... (((

Так ты выложи на англоязычном сайте в виде компонента-плагина, возможно кто-то возьмется допилить. Тут 1,5 человека в неделю ходят - конечно все заглохнет.