Używanie @since w kodzie PHP

Question

Używam komentarza @since w moim kodzie PHP. Mam jednak pytanie dotyczące jego użycia. Załóżmy, że mam funkcję, która wykonuje określone zadanie i została zaimplementowana w wersji 1.0.

Obecnie mam @since 1.0.

Teraz idę do przodu i zmień nazwę funkcji, chociaż kod w środku pozostaje taki sam. Czy powinien teraz mówić @since 3.0 (aktualna wersja) lub pozostać @since 1.0?

Answer 1

Nazwa funkcji nie istniała w wersji 1.0, dlatego @since powinno mieć wartość 3.0. Nie ma znaczenia, że ​​inaczej nazwana funkcja zapewnia taką samą funkcjonalność w starej wersji; nie będziesz mógł użyć nowej nazwy w starej wersji. docs powiedzieć:

Zastosowanie @since dokumentowania korekt, jak w „Funkcja ta jest częścią tego pakietu od wersji 2.0”

Celem @since jest powiedzieć komuś za pomocą pakietu, który „od wersji x, funkcja o nazwie foo istnieje. Jeśli pójdziesz i zmienić foo do bar w v3 ale pozostawić @since jako V1, a następnie swoje dokumenty będą nieprawidłowo stwierdzić, że jest to bezpieczne, aby zadzwonić bar() w v1. w rzeczywistości, nie było bar() w wersji 1, a wywołanie spowodowałoby błąd.

Możesz również rozważyć zachowanie kodu funkcyjnego ze starą nazwą (która po prostu wywołuje prawdziwą funkcję) i oznaczenie go jako @deprecated.

Answer 2

ponieważ jest sprawdzonym phpDoc tag

tagi PHPDoc pracować z niektórych redaktorów, aby wyświetlić więcej informacji o kawałek kodu. Przydaje się programistom używającym tych edytorów do zrozumienia celu i miejsca, w którym będą go używać w swoim kodzie.

Konwencja zezwalająca na blokowanie PHPdoc ma mieć informacje @ (nawet jeśli nie są dostępne w tym czasie) i informacje o pakiecie, które zawsze powinny być "WordPress", chyba że jest to biblioteka zewnętrzna. jak po

/** 
* ... Description(s) here 
* 
* @package WordPress 
* @since 2.1 or {@internal Unknown}} 
* 
* ... More information if needed. 
*/ 

Proszę przeczytać następujące artykuły Więcej informacji na temat tagów PHPDoc

PHPDocumentor 0.4.1

Document when (at which version) an element was first added to a package

phpDocumentor Tutorial

phpDocumentor tags - How to use tags in DocBlocks

@since - phpDocumentor

Answer 3

Znacznik @since wskazuje, z którą wersją udostępniono powiązane elementy konstrukcyjne.

Składnia

@since [version] [<description>] 

Znacznik @since może być używany do wskazania od której wersji Poszczególne elementy strukturalne stały się dostępne.

Informacje te mogą zostać wykorzystane do wygenerowania zestawu Dokumentacji API, w których konsument jest informowany, która wersja aplikacji jest niezbędna dla określonego elementu.

Wersja MUSI spełniać te same zasady, co wektor znaczników @version i MOGĄ mieć opis w celu zapewnienia dodatkowych informacji.

Ten znacznik może występować wiele razy w obrębie PHPDoc. W takim przypadku każde wystąpienie jest traktowane jako wpis do dziennika zmian. ZALECA SIĘ, aby każdy opis zawierał opis.

Przykład

/** 
    * @since 1.0.1 First time this was introduced. 
    * 
    * @return integer Indicates the number of items. 
    */ 
function count() 
{ 
    <...> 
} 

/** 
    * @since 1.0.2 Added the $b argument. 
    * @since 1.0.1 Added the $a argument. 
    * @since 1.0.0 
    * 
    * @return void 
    */ 
function dump($a, $b) 
{ 
    <...> 
}