API Dokumentacijos Gairės

1 RDoc

Rails API dokumentacija generuojama naudojant RDoc. Norėdami ją sugeneruoti, įsitikinkite, kad esate Rails šakninėje direktorijoje, paleiskite bundle install ir vykdykite:

$ bundle exec rake rdoc

Sugeneruoti HTML failai rasomi ./doc/rdoc direktorijoje.

PASTABA: Norint gauti pagalbą dėl sintaksės, prašome pasikonsultuoti su RDoc Markup Reference.

2 Nuorodos

Rails API dokumentacija nėra skirta peržiūrėti GitHub'e, todėl nuorodos turėtų naudoti RDoc link žymėjimą atsižvelgiant į esamą API.

Tai yra dėl skirtumų tarp GitHub Markdown ir sugeneruoto RDoc, kuris yra publikuojamas adresu api.rubyonrails.org ir edgeapi.rubyonrails.org.

Pavyzdžiui, naudojame [link:classes/ActiveRecord/Base.html] nuorodą į ActiveRecord::Base klasę, sugeneruotą RDoc.

Tai yra pageidautina nei absoliučios nuorodos, pvz., [https://api.rubyonrails.org/classes/ActiveRecord/Base.html], kuri išvestų skaitytoją iš dabartinės dokumentacijos versijos (pvz., edgeapi.rubyonrails.org).

3 Formulavimas

Rašykite paprastus, deklaratyvius sakinio struktūras. Trumpumas yra pliusas: pereikite prie esmės.

Rašykite dabarties laiku: "Gražina hash'ą, kuris...", o ne "Gražino hash'ą, kuris..." arba "Gražins hash'ą, kuris...".

Komentarus pradėkite didžiąja raide. Laikykitės įprastų skyrybos taisyklių:

# Deklaruoja atributo skaitytuvą, kuris remiasi viduje pavadintu
# kintamuoju.
def attr_internal_reader(*attrs)
  # ...
end

Skaitytojui perteikite dabartinį veikimo būdą, tiek aiškiai, tiek neaiškiai. Naudokite rekomenduojamus idiomus. Jei reikia, pertvarkykite skyrius, kad būtų pabrėžti pageidaujami požiūriai ir pan. Dokumentacija turėtų būti modelis geriausioms praktikoms ir kanoniškam, moderniam Rails naudojimui.

Dokumentacija turi būti trumpa, bet išsamiai. Ištyrinkite ir aprašykite ribinius atvejus. Kas nutinka, jei modulis yra anoniminis? Kas nutinka, jei kolekcija yra tuščia? Kas nutinka, jei argumentas yra nil?

Rails komponentų pavadinimai turi tarpą tarp žodžių, pvz., "Active Support". ActiveRecord yra Ruby modulis, o Active Record yra ORM. Visos Rails dokumentacijos turėtų nuosekliai nuorodyti į Rails komponentus pagal jų tikrus pavadinimus.

Kalbant apie "Rails aplikaciją", priešingai nei "engine" ar "plugin", visada naudokite "application". Rails aplikacijos nėra "paslaugos", nebent konkretaus aptariamojo paslaugų orientuoto architektūros atveju.

Rašykite pavadinimus teisingai: Arel, minitest, RSpec, HTML, MySQL, JavaScript, ERB, Hotwire. Jei abejojate, prašome pasitikrinti autoritetingą šaltinį, pvz., jų oficialią dokumentaciją.

Pirmenybę teikite formulavimui, kuriame nėra "you" ir "your". Pavyzdžiui, vietoj

If you need to use `return` statements in your callbacks, it is recommended that you explicitly define them as methods.

naudokite šį stilių:

If `return` is needed, it is recommended to explicitly define a method.

Tačiau, naudojant įvardžius atsižvelgiant į hipotetinį asmenį, pvz., "vartotojas su sesijos slapukais", reikėtų naudoti lyties neutralius įvardžius (they/their/them). Vietoje:

he arba she... naudokite they.
him arba her... naudokite them.
his arba her... naudokite their.
his arba hers... naudokite theirs.
himself arba herself... naudokite themselves.

4 Anglų kalba

Prašome naudoti Amerikos anglų kalbą (color, center, modularize, ir pan.). Žr. čia Amerikos ir Britų anglų kalbos rašybos skirtumų sąrašą.

5 Oxford kablelis

Prašome naudoti Oxford kablelį ("red, white, and blue", o ne "red, white and blue").

6 Pavyzdžio kodas

Pasirinkite prasmingus pavyzdžius, kurie atspindi ir apima pagrindinius dalykus bei įdomius momentus ar klaidas.

Kodo gabalams įrėminti naudokite dvi tarpas--tai yra, žymint žymėjimo tikslais, dvi tarpas atsižvelgiant į kairįjį kraštinę. Patys pavyzdžiai turėtų naudoti Rails kodavimo konvencijas.

Trumpiems dokumentams nereikia aiškiai nurodyti "Pavyzdžiai" žymės, kad būtų įterpti fragmentai; jie tiesiog seka po pastraipų:

# Converts a collection of elements into a formatted string by
# calling +to_s+ on all elements and joining them.
#
#   Blog.all.to_fs # => "First PostSecond PostThird Post"

Kita vertus, dideliems struktūruotiems dokumentams gali būti atskiras "Pavyzdžiai" skyrius:

# ==== Examples
#
#   Person.exists?(5)
#   Person.exists?('5')
#   Person.exists?(name: "David")
#   Person.exists?(['name LIKE ?', "%#{query}%"])

Rezultatai išraiškų seka juos seka ir pristatoma "# => ", vertikaliai išlyginta:

# Tikrinant, ar sveikasis skaičius yra lyginis ar nelyginis.
#
#   1.even? # => false
#   1.odd?  # => true
#   2.even? # => true
#   2.odd?  # => false

Jei eilutė per ilga, komentaras gali būti perkeltas į kitą eilutę:

#   label(:article, :title)
#   # => <label for="article_title">Title</label>
#
#   label(:article, :title, "A short title")
#   # => <label for="article_title">A short title</label>
#
#   label(:article, :title, "A short title", class: "title_label")
#   # => <label for="article_title" class="title_label">A short title</label>

Vengti naudoti spausdinimo metodus, pvz., puts ar p, tam tikslui.

Kita vertus, įprasti komentarai nenaudoja rodyklės:

#   polymorphic_url(record)  # tas pats kaip comment_url(record)

6.1 SQL

Dokumentuojant SQL teiginius, rezultatas neturi turėti => prieš išvestį.

Pavyzdžiui,

#   User.where(name: 'Oscar').to_sql
#   # SELECT "users".* FROM "users"  WHERE "users"."name" = 'Oscar'

6.2 IRB

Dokumentuojant elgesį su IRB, Ruby interaktyviu REPL, visada prieš komandas naudokite prefiksą irb> ir išvestis turi būti su prefiksu =>.

Pavyzdžiui,

# Rasti klientą su pagrindiniu raktu (id) 10.
#   irb> customer = Customer.find(10)
#   # => #<Customer id: 10, first_name: "Ryan">

6.3 Bash / komandinė eilutė

Komandinės eilutės pavyzdžiams visada prieš komandą naudokite $, išvestis neturi turėti jokio prefikso.

# Paleiskite šią komandą:
#   $ bin/rails new zomg
#   ...

7 Booleans

Predikatuose ir vėliavose pageidautina dokumentuoti boolean semantiką, o ne tikslų reikšmes.

Kai "true" arba "false" naudojami, kaip apibrėžta Ruby, naudokite įprastą šriftą. Vienetiniai true ir false reikalauja fiksuoto pločio šrifto. Prašome vengti terminų, tokio kaip "truthy", Ruby apibrėžia, kas yra tiesa ir netiesa kalboje, todėl šie žodžiai turi techninį prasmės ir nereikalauja jokių pakaitų.

Taisyklės pagalba nereikia dokumentuoti vienetinių, nebūtina. Tai neleidžia dirbtiniams konstruktams, tokiam kaip !! ar ternariniai operatoriai, leidžia atlikti pertvarkymus ir kodas neturi remtis tiksliais grąžinamų metodų reikšmėmis, kurie yra iškviesti įgyvendinime.

Pavyzdžiui:

`config.action_mailer.perform_deliveries` nurodo, ar paštas iš tikrųjų bus pristatomas ir pagal numatytuosius nustatymus yra tiesa

vartotojui nereikia žinoti, kokia yra vėliavos numatytoji reikšmė, todėl dokumentuojame tik jos boolean semantiką.

Pavyzdys su predikatu:

# Grąžina true, jei kolekcija yra tuščia.
#
# Jei kolekcija yra įkelta
# tai yra lygu <tt>collection.size.zero?</tt>. Jei
# kolekcija nebuvo įkelta, tai yra lygu
# <tt>!collection.exists?</tt>. Jei kolekcija dar nebuvo
# įkelta ir jūs vis tiek ketinate gauti įrašus, geriau
# patikrinkite <tt>collection.length.zero?</tt>.
def empty?
  if loaded?
    size.zero?
  else
    @target.blank? && !scope.exists?
  end
end

API atsargus neprisiima jokios konkretaus reikšmės, metodas turi predikato semantiką, tai pakanka.

8 Failų pavadinimai

Taisyklės pagalba naudokite failų pavadinimus, susijusius su programos šaknimi:

config/routes.rb            # TAIP
routes.rb                   # NE
RAILS_ROOT/config/routes.rb # NE

9 Šriftai

9.1 Fiksuoto pločio šriftas

Naudokite fiksuoto pločio šriftus:

Konstantoms, ypač klasės ir modulio pavadinimams.
Metodų pavadinimams.
Literalomis, tokiais kaip nil, false, true, self.
Simboliais.
Metodų parametrais.
Failų pavadinimais.

class Array
  # Iškviečia +to_param+ visuose savo elementuose ir sujungia rezultatą su
  # pasviraisiais brūkšniais. Tai naudojama +url_for+ veiksmo pakete.
  def to_param
    collect { |e| e.to_param }.join '/'
  end
end

ĮSPĖJIMAS: Naudoti +...+ fiksuoto pločio šriftui veikia tik su paprastu turiniu, tokiais kaip įprastos klasės, modulio, metodo pavadinimai, simboliai, keliai (su įstrižainėmis brūkšneliais) ir kt. Prašome naudoti <tt>...</tt> visam kitam turiniui.

RDoc išvestį galite greitai patikrinti naudodami šią komandą:

$ echo "+:to_param+" | rdoc --pipe
# => <p><code>:to_param</code></p>

Pavyzdžiui, kodas su tarpais ar kabutėmis turėtų naudoti formą <tt>...</tt>.

9.2 Įprastas šriftas

Kai "true" ir "false" yra anglų žodžiai, o ne Ruby raktiniai žodžiai, naudokite įprastą šriftą:

# Paleidžia visas patikras nurodytoje kontekste.
# Grąžina true, jei klaidų nerasta, false kitu atveju.
#
# Jei argumentas yra false (numatytasis yra +nil+), kontekstas yra
# nustatomas į <tt>:create</tt>, jei <tt>new_record?</tt> yra true,
# ir į <tt>:update</tt>, jei nėra.
#
# Patikros be <tt>:on</tt> parinkties bus vykdomos
# nepriklausomai nuo konteksto. Patikros su # kai kuriais <tt>:on</tt>
# parinktimis bus vykdomos tik nurodytame kontekste.
def valid?(context = nil)
  # ...
end

10 Aprašymo sąrašai

Sąrašuose su pasirinkimais, parametrais ir kt. tarp elemento ir jo aprašymo naudokite brūkšnį (geriau skaitosi nei dvitaškis, nes paprastai pasirinkimai yra simboliai):

# * <tt>:allow_nil</tt> - Praleisti patikrinimą, jei atributas yra +nil+.

Aprašymas prasideda didžiąja raide ir baigiasi tašku - tai standartinė anglų kalba.

Alternatyvus požiūris, kai norite pateikti papildomų detalės ir pavyzdžių, yra naudoti parinkčių skyriaus stilių.

ActiveSupport::MessageEncryptor#encrypt_and_sign yra puikus šio pavyzdžio pavyzdys.

# ==== Parinktys
#
# [+:expires_at+]
#   Laikas, kada žinutė pasibaigs. Po šio laiko žinutės patikrinimas
#   nepavyks.
#
#     message = encryptor.encrypt_and_sign("hello", expires_at: Time.now.tomorrow)
#     encryptor.decrypt_and_verify(message) # => "hello"
#     # Po 24 valandų...
#     encryptor.decrypt_and_verify(message) # => nil

11 Dinamiškai generuojami metodai

Metodai, sukurti naudojant (module|class)_eval(STRING), turi komentarą šalia su sugeneruoto kodo pavyzdžiu. Šis komentaras yra 2 tarpai nuo šablono:

Jei rezultatas yra per platus, pvz., 200 stulpelių ar daugiau, komentarą padėkite virš kvietimo:

# def self.find_by_login_and_activated(*args)
#   options = args.extract_options!
#   ...
# end
self.class_eval %{
  def self.#{method_id}(*args)
    options = args.extract_options!
    ...
  end
}, __FILE__, __LINE__

12 Metodo matomumas

Rašant dokumentaciją Rails, svarbu suprasti skirtumą tarp viešo naudotojo sąsajos ir vidinės sąsajos.

Rails, kaip ir dauguma bibliotekų, naudoja privataus raktažodį iš Ruby vidinei sąsajai apibrėžti. Tačiau viešoji sąsaja laikosi šiek tiek kitokio konvencijos. Vietoj to, kad būtų priimta, jog visi vieši metodai skirti naudotojui, Rails naudoja :nodoc: direktyvą, kad pažymėtų šios rūšies metodus kaip vidinę sąsają.

Tai reiškia, kad yra metodų Rails su public matomumu, kurie nėra skirti naudotojui.

Pavyzdys to yra ActiveRecord::Core::ClassMethods#arel_table:

module ActiveRecord::Core::ClassMethods
  def arel_table # :nodoc:
    # padaryti kažką magiško..
  end
end

Jei pagalvojote, "šis metodas atrodo kaip viešas klasės metodas ActiveRecord::Core", buvote teisus. Tačiau iš tikrųjų Rails komanda nenori, kad naudotojai pasitikėtų šiuo metodu. Todėl jie pažymi jį kaip :nodoc: ir jis pašalinamas iš viešos dokumentacijos. Tokio sprendimo priežastis yra leisti komandai keisti šiuos metodus pagal jų vidines poreikius per išleidimus, kaip jie mano tinkamus. Šio metodo pavadinimas gali pasikeisti, arba grąžinimo reikšmė, arba visa klasė gali išnykti; nėra jokios garantijos, todėl neturėtumėte priklausyti nuo šios sąsajos savo įskiepiuose ar programose. Kitu atveju rizikuojate, kad jūsų programa ar juvelyras suges, kai atnaujinsite naujesnę Rails versiją.

Kaip bendradarbis, svarbu pagalvoti, ar ši sąsaja skirta galutiniam naudotojui. Rails komanda įsipareigoja nepakeisti viešos sąsajos per išleidimus be pilno pasenusio ciklo. Rekomenduojama :nodoc: pažymėti bet kurį vidinį jūsų metodą/klasę, nebent jie jau yra privačios (tai reiškia matomumą), tuomet jie pagal nutylėjimą yra vidinės. Kai sąsaja stabilizuojasi, matomumas gali pasikeisti, tačiau viešos sąsajos keitimas yra daug sunkesnis dėl suderinamumo atgal.

Klasė ar modulis pažymimas :nodoc:, kad būtų nurodyta, jog visi metodai yra vidinė sąsaja ir jais neturėtų būti naudojamasi tiesiogiai.

Apibendrinant, Rails komanda naudoja :nodoc:, kad pažymėtų viešai matomus metodus ir klases kaip vidinę sąsają; API matomumo pakeitimai turėtų būti apgalvoti ir aptarti per pull request'ą.

13 Dėl Rails steko

Dokumentuojant dalis iš Rails API, svarbu prisiminti visas dalis, kurios sudaro Rails steką.

Tai reiškia, kad elgsena gali keistis priklausomai nuo metodo ar klasės konteksto ar srities, kurią bandote dokumentuoti.

Skirtingose vietose yra skirtinga elgsena, kai atsižvelgiame į visą steką, vienas tokių pavyzdžių yra ActionView::Helpers::AssetTagHelper#image_tag:

# image_tag("icon.png")
#   # => <img src="/assets/icon.png" />

Nors numatytoji #image_tag elgsena visada yra grąžinti /images/icon.png, atsižvelgiant į visą Rails steką (įskaitant turinio rinkinį), galime matyti aukščiau pateiktą rezultatą.

Mums rūpi tik elgsena, patiriama naudojant visą numatytąjį Rails steką.

Šiuo atveju norime dokumentuoti framework'o elgseną, o ne tik šį konkretų metodą.

Jei turite klausimų, kaip Rails komanda tvarko tam tikrą API, nebijokite atidaryti užklausos arba siųsti pataisymą į problemos sekimo sistemą.

Atsiliepimai

Jūs esate skatinami padėti pagerinti šio vadovo kokybę.

Prašome prisidėti, jei pastebite rašybos klaidų ar faktinių klaidų. Norėdami pradėti, galite perskaityti mūsų dokumentacijos prisidėjimo skyrių.

Taip pat gali būti nepilnos informacijos arba informacijos, kuri nėra atnaujinta. Prašome pridėti bet kokią trūkstamą dokumentaciją pagrindiniam. Patikrinkite Edge vadovus pirmiausia, ar problemas jau išspręsta arba ne pagrindinėje šakoje. Patikrinkite Ruby on Rails vadovų gaires dėl stiliaus ir konvencijų.

Jei dėl kokios nors priežasties pastebite kažką, ką reikia ištaisyti, bet negalite patys tai pataisyti, prašome pranešti apie problemą.

Ir galiausiai, bet ne mažiau svarbu, bet koks diskusijos dėl Ruby on Rails dokumentacijos yra labai laukiamos oficialiame Ruby on Rails forume.

Chapters

Atsiliepimai