Piszę pakiet R, a ja dokumentuję wszystkie moje funkcje z roxygen2. Jednak nie chcę, aby wszystkie funkcje pojawiały się w instrukcji pakietu. Jak mogę określić, które funkcje powinny pojawiać się w podręczniku pakietu, a które nie?Funkcja wykluczająca z instrukcji obsługi pakietu R
Mam świadomość, że nazwa funkcji z wiodącą kropką, np. .f <- function() zamiast f <- function() jest rozwiązaniem. Czy są inne rozwiązania?
I przeoczył następujące szczegółowo w znakomitej książce R packages przez Hadley Wickham (w części dotyczącej dokumentacji Object):
@keywords keyword1 kluczowe2 ... dodaje standaryzowane kluczowych. Słowa kluczowe są opcjonalne, ale jeśli są obecne, należy je pobrać z predefiniowanej listy znajdującej się w file.path (R.home ("doc"), "KEYWORDS").
Ogólnie, słowa kluczowe nie są użyteczne, z wyjątkiem pozycji wewnętrznych @keywords. Korzystanie z wewnętrznego słowa kluczowego powoduje usunięcie funkcji z indeksu pakietów i wyłącza niektóre z ich automatycznych testów. Powszechne jest używanie @keywords internal do funkcji, które są interesujące dla innych programistów rozszerzających pakiet, ale nie dla większości użytkowników.
@keywords internal więc dodanie do funkcji roxygen2 dokumentacji wyników w funkcji nie występujące w pakiecie ręcznym/indeksu, a jednocześnie dzięki czemu strona pomocy będzie dostępny po załadowaniu pakietu.
+1 do wykrywania '@keywords wewnętrznych. Nie chcę nudzić ludzi za pomocą moich wewnętrznych funkcji pomocnika, dziękuję! – keberwein
Dlaczego je dokumentować, jeśli nie chcesz, aby były w instrukcji? – nrussell
Ponieważ jest to przydatne zarówno dla mnie, gdy przypominam sobie funkcje, jak i dla innych, którzy mogą chcieć używać "ukrytych" funkcji. Sądzę, że widziałem przykłady w innych pakietach, w których nie mogłem znaleźć strony pomocy funkcji, pisząc '? Nazwa_funkcji' w konsoli po zaimportowaniu pakietu, ale mogłem zobaczyć stronę pomocy, jeśli napisałem'? Pkgname: :: function_name'. Mogłem jednak pamiętać, że się myliłem. –
Ale funkcje dostępne za pomocą ':::' nie są eksportowane z pakietów - co zwykle oznacza, że autor nie zamierzał używać tej funkcji przez klientów. Zasadniczo takie funkcje nie są dokumentowane - np. 'tools :::. is_ASCII'. Przypuszczam, że jeśli napotkałeś funkcję nie wyeksportowaną, która * zawiera * dokumentację, najprawdopodobniej była to funkcja eksportowana (i udokumentowana) i usunięta z listy eksportu w późniejszej wersji. – nrussell