Лучшая практика использования @package и @since в разветвленном проекте - PullRequest
Новая
       29

Лучшая практика использования @package и @since в разветвленном проекте

0 голосов
/ 10 января 2019

Мой проект использует FoundationPress, начальную тему WordPress. Я использую Github и обновляю свой проект из родительского репозитория на upstream remote, когда сообщество улучшает код. Кстати, я программировал долгое время, но почти всегда один, и я очень неопытен с докблоками и документацией в коде. Я знаю, что в какой-то степени это может быть основано на мнении, поскольку это, кажется, тенденция поиска других ответов, но я чувствую, что не понимаю правильного использования.

Родительский проект использует PHP Docblocks, которые выглядят так на PHP-файлах, всегда только один раз на файл, например: 

/**
 * Brief File Description
 *
 * @package FoundationPress
 * @since FoundationPress 1.0.0
 */

Когда я добавляю новые собственные файлы PHP, я добавляю похожий блок, но вместо этого использую имя для своего проекта: 

/**
 * Brief File Description
 *
 * @package MyProject
 * @since MyProject 0.1.0
 */

Иногда я обновляю существующий файл своими собственными функциями. Я поставил @since над этими функциями, поэтому это выглядит так: 

/**
 * Brief File Description
 *
 * @package FoundationPress
 * @since FoundationPress 1.0.0
 */

function foo() { ... }

function bar() { ... }

/**
 * My Function Description 
 *
 * @since MyProject 0.1.0
*/
function my_foo() { ... }

В других случаях я обновляю существующую функцию - я просто оставляю для них один докблок, но мне интересно, стоит ли мне что-то обновлять.

  1. Есть ли передовая практика или, по крайней мере, общепринятый способ справиться с этой ситуацией (разветвленный проект, который постоянно обновляется со своим родительским репозиторием), поэтому мой код более полезен для других программистов?
  2. Кажется, есть много других параметров и параметров докблока, например, докблока для каждой функции. Есть ли рекомендуемый уровень детализации, к которому я должен стремиться?
  3. Есть ли рекомендация по добавлению аналогичной документации по другим типам файлов (SCSS, JS и т. Д.) В мой проект? Похоже, что в родительском проекте их нет, но мне было бы интересно добавить их.

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

...