2015-12-20 12 views
5

mogę udokumentować funkcję tak:dokumentowania REBOL za dialekt

f: func [ 
    "a description" 
    arg1 [string!] "a description of an argument 1" 
    ][ 
    arg1 
    ] 

mogę używać ?/help w celu pobrania informacji o funkcji (opis, do użycia, listę argumentów, opis każdy argument i jego typ)

? f 
USAGE: 
    F arg1 

DESCRIPTION: 
    a description 
    F is a function value. 

ARGUMENTS: 
    arg1 -- a description of an argument 1 (Type: string) 

Nie mogę dokumentować takich dialektów. Czy istnieje automatyczny sposób dokumentowania dialektów (jak robi to func)? Czy muszę to robić ręcznie?

Odpowiedz

4

Nie ma w tej chwili nic, ale to dobry pomysł. Tak dobrze, że wcześniej było to someone has suggested it. :-)

Czy muszę to zrobić ręcznie?

Możesz ręcznie napisać nowy generator, który definiuje twój format "dialekt spec". Następnie wykonaj komendę HELP lub pomóż HELP, aby ją rozpoznać.

Bardzo krótki przykład wykazać grupę technik, które mogą się przydać w robienie czegoś jak ten (nie wszystkie oczekuje się być oczywiste, raczej wskazywać na elastyczność):

make-dialect: function [spec [block!] body [block!]] [ 
    return function ['arg [block! word!]] compose/deep/only [ 
     case [ 
      arg = 'HELP [ 
       foreach keyword (spec/keywords) [ 
        print [keyword "-" {your help here}] 
       ] 
      ] 

      block? arg [ 
       do func [arg] (body) arg 
      ] 

      'default [ 
       print "Unrecognized command. Try HELP." 
      ] 
     ] 
    ] 
] 

Więc nie twoja funkcja, która przyjmuje specyfikację dialektu i pełni funkcję. Gdy masz generator, przy użyciu może być mniejsza instrukcja:

mumble: make-dialect [keywords: [foo baz bar]] [ 
    print ["arg is" mold arg] 
] 

>> mumble help 
foo - your help here 
baz - your help here 
bar - your help here 

>> mumble [<some> [dialect] {stuff}] 
arg is [<some> [dialect] {stuff}] 

Techniki stosowane są tu:

  • Miękkie Cytowanie - Zwykle trzeba by powiedzieć mumble 'help do „cytat "pomoc jako słowo pisane! aby przekazać to słowo! mumble (w przeciwieństwie do uruchamiania domyślnego polecenia HELP). Ale ponieważ arg został zadeklarowany w wygenerowanej funkcji jako 'arg, był "miękko cytowany" ... oznacza to, że słowa i ścieżki nie będą oceniane. (Parens, get-words i get-paths nadal będą.) To kompromis, ponieważ oznacza to, że jeśli ktoś ma zmienną, którą chce przekazać, musi powiedzieć : var lub (var) jako argument zamiast tylko var (wyobraźcie sobie, że blok do przekazania dialektu jest zmienny), więc niekoniecznie chcecie go użyć ... ale pomyślałem, że to ciekawe demo, aby mumble help działało bez słowa!

  • Głębokie Skład - The spec i body zmienne, które są przekazywane do make-dialect istnieć tylko tak długo, jak make-dialect jest uruchomiony. Gdy to się skończy, znikną. Więc nie możesz zostawić tych słów w ciele funkcji, którą generujesz. Wykorzystuje to funkcję COMPOSE/DEEP do oceny parens w ciele przed uruchomieniem generatora funkcji w celu uzyskania wyniku, efektywnego wydobywania danych z bloków i łączenia ich w strukturę ciała funkcji.

  • Binding Pracuj Ponowne użycie funkcyjnego - Wygenerowany funkcja ma spec z parametrem arg że nie istnieje w miejscu połączenia z make-dialect. Więc argument musi być odbiciem, ale co? Można to zrobić ręcznie, ale jednym z łatwych sposobów jest umożliwienie FUNC wykonania pracy za ciebie.

Są to niektóre z technik, które byłyby stosowane w proponowanym rozwiązaniu, które ma na celu nie tylko języka dokumentu, ale zapewniają łatwą metodę, dzięki której ich słowa kluczowe może być ponownie odwzorowane (np jeśli czyjaś System REBOL został skonfigurowany dla innego języka mówionego).

Powiązane problemy