Dlaczego wymagana jest składnia ": nodoc:"?

Question

Wydaje się dużo libraries/wtyczek użyć tej składni:

def self.included(base) # :nodoc: 
    base.extend ClassMethods 
    end 

Dlaczego :nodoc: część konieczne?

Answer 1

Nie jest to konieczne. Jeśli zastosuje się do klasy, po prostu pomija dokumentację (rdoc) dla wszystkich metod w rozszerzeniu klasy. Opisane w programowaniu Ruby jako:

: nodoc: - Nie zawierają ten element w dokumentacja. W przypadku klas i modułów metody, aliasy, stałe i atrybuty bezpośrednio w obrębie klasy lub modułu również zostaną pominięte w dokumentacji . Domyślnie zostaną udokumentowane moduły i klasy z klasy lub klasy.

Answer 2

Nie sądzę, że to konieczne. Właściwie to, moim zdaniem, jest to jedna z najbardziej bezużytecznych funkcji RDoc.

Tyle razy widziałem to podczas czytania kodu libarie i musiałem zadać sobie pytanie "dlaczego?". Nie widzę powodu, aby korzystać z tej funkcji. Jeśli nie chcesz, aby ludzie używali Twojej metody, po prostu uczyń ją prywatną. To bardzo kłopotliwe, gdy czytasz dokumentację i widzisz wywołanie metody do metody, której nie ma w dokumentacji.