Accept misused :nodoc: usage

Aperta
  • Qualcosa non va?
#1,578 0 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
ruby
Ambito
documentation

Direzione di ricerca

Usa gli esempi Ruby nell’issue come casi di riproduzione e traccia il parsing e il comportamento di associazione delle direttive di RDoc. Confronta la gestione attuale con le categorie proposte di contenitore, dipendenti dalla situazione e di oggetto di codice, incluso il comportamento degli avvisi per le direttive miste. Il lavoro è completato quando gli esempi vengono risolti nel contenitore o nell’oggetto di codice previsto e le combinazioni non valide generano un avviso.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Usage of these :nodoc: are not correct but frequently misused. Maybe it's better to apply :nodoc: to the CodeObject next line.

class Foo

  # :nodoc: (This :nodoc: is applied to class Foo, not to method bar)
  def bar; end

  # :nodoc: (Same as above)
  def baz; end
end

Correct usage is:

class Foo
  # :nodoc: (for class Foo)

  def bar
  end

  def baz # :nodoc: (for method baz)
  end
end

This behavior looks like a bug.

class Foo

  # This is a comment for method bar
  # :nodoc: (this is a nodoc directive for class Foo)
  # :call-seq: bar(x, y) (this is a call-seq directive for method bar)
  # This is also a coment for method bar
  def bar
  end
end

Suggestion

If comment only contains container directive(including :nodoc:) and it appears at first line in class/module, it is a directive for container itself.

class Foo
  # :nodoc: (for container)
  # :stopdoc: (for container)

  def foo; end
end

If a comment before code object contains container directive(except :nodoc:), it's for container

class Foo
  ...

  # :stopdoc: (for container)

  def foo; end
end

Other comments are for code object. If it contains container directive(except :nodoc:), it's an error to be warned.

class Foo
  # :nodoc: (for method)
  # comment

  def foo; end

  # :nodoc: (for method)

  def foo; end
end

Directive categories

Directive categorization will be a bit complicated, but I think it's worth clarifying it.

Container directive

Must not mix with code object directives, comment containing these directives must not associated with code object.
:startdoc: :stopdoc: :enddoc: :doc: :category:

Container special directive

Must not mix with code object directives. Comment text is specially handled.
:section:

Situation dependent directive

Can be both container directive or code object directive
:nodoc:

CodeObject directive

Other directives. :callseq: :yield: and also unknown ones.

Lingua principale
Ruby
Stelle
928
Fork
471
Merge medio
2g 4m
PR unite (30g)
13

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ruby/rdoc

Tutte le issue di ruby/rdoc

Issue simili

Altre issue su Ruby

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.