Docstring

W programowaniu dokumentacja to literał łańcuchowy określony w kodzie źródłowym , który jest używany, podobnie jak komentarz , do dokumentowania określonego segmentu kodu. W przeciwieństwie do konwencjonalnych komentarzy do kodu źródłowego, a nawet specjalnie sformatowanych komentarzy, takich jak docblocks , ciągi dokumentacyjne nie są usuwane z drzewa źródłowego podczas jego analizowania i są zachowywane przez cały czas działania programu. Dzięki temu programista może przeglądać te komentarze w czasie wykonywania, na przykład jako interaktywny system pomocy lub jako metadane .

Języki obsługujące docstringi to Python , Lisp , Elixir , Clojure , Gherkin , Julia i Haskell .

Przykłady realizacji

Eliksir

Dokumentacja jest obsługiwana na poziomie językowym w formie docstringów. Markdown jest de facto wybranym językiem znaczników Elixira do użytku w dokumentach:

   
   
  
  

   
    
    
  
 def  module  MyModule  do  @moduledoc  """  Dokumentacja mojego modułu. Z **formatowaniem**.  """  @doc  "Hello"  def  world  do  "World"  end  end

Seplenienie

W Lispie ciągi dokumentów są znane jako ciągi dokumentacji. Standard Common Lisp stwierdza, że ​​konkretna implementacja może odrzucić dokumenty, kiedy tylko zechcą, z dowolnego powodu. Kiedy są przechowywane, ciągi dokumentów można przeglądać i zmieniać za pomocą funkcji DOKUMENTACJA. Na przykład: 

     
      (  defun  foo  ()  "cześć"  zero  )  (  dokumentacja  #'  foo  'funkcja  )  =>  "cześć"

Pyton

Powszechna praktyka dokumentowania obiektu kodu na początku jego definicji została uchwycona przez dodanie składni docstring w języku Python.

Docstring dla obiektu kodu Pythona (modułu, klasy lub funkcji) to pierwsza instrukcja tego obiektu kodu, bezpośrednio po definicji (instrukcja „def” lub „class”). Instrukcja musi być czystym literałem łańcuchowym, a nie jakimkolwiek innym rodzajem wyrażenia. Dokumentacja dla obiektu kodu jest dostępna w __doc__ tego obiektu kodu oraz poprzez funkcję pomocy .

Poniższy plik Pythona przedstawia deklarację docstringów w pliku źródłowym Pythona:



 
    

     
        

 
     """Dokumentacja modułu"""  class  MyClass  :  """Dokumentacja klasy"""  def  my_method  (  self  ):  """Dokumentacja metody"""  def  my_function  ():  """Dokumentacja funkcji"""

Zakładając, że powyższy kod został zapisany jako mymodule.py , poniżej znajduje się interaktywna sesja pokazująca, w jaki sposób można uzyskać dostęp do dokumentów: 

 








 >>>  import  mymodule  >>>  help  (  mymodule  )  Docstring modułu  >>>  help  (  mymodule  .  MyClass  )  Docstring klasy  >>>  help  (  mymodule  .  MyClass  .  my_method  )  Docstring metody  >>>  help  (  mymodule  .  my_function  )  Dokumentacja funkcji  >>>

Narzędzia używające docstringów

Zobacz też

Linki zewnętrzne

Pobrano z „ https://en.wikipedia.org/w/index.php?title=Docstring&oldid=1104443495 ”