positron-solutions / transient-showcase

Example forms for transient UI's in Emacs
GNU General Public License v3.0
213 stars 22 forks source link

checkdoc warnings #4

Closed progfolio closed 1 year ago

progfolio commented 1 year ago

checkdoc reports the following:

transient-showcase.el        55  14 note     e-f-c    First sentence should end with punctuation
transient-showcase.el       974   2 note     e-f-c    Argument ‘layout-child’ should appear (as LAYOUT-CHILD) in the doc string
transient-showcase.el       994   2 note     e-f-c    Argument ‘prompt’ should appear (as PROMPT) in the doc string
transient-showcase.el      1023   2 note     e-f-c    Argument ‘obj’ should appear (as OBJ) in the doc string
transient-showcase.el      1032   2 note     e-f-c    Argument ‘obj’ should appear (as OBJ) in the doc string
transient-showcase.el      1043   2 note     e-f-c    Argument ‘obj’ should appear (as OBJ) in the doc string
transient-showcase.el      1051   2 note     e-f-c    Argument ‘obj’ should appear (as OBJ) in the doc string
psionic-k commented 1 year ago

I don't agree with checkdoc's idea of documenting cl-defmethod excessively. The type information comes from the next argument, which is also self-explanatory. Transient itself also does not use this style. Remaining nits accounted for in inbound changes.

progfolio commented 1 year ago

I wouldn't consider it excessive documentation. The name obj is too generic IMO. It could be replaced with a more specific description of what the object represents. That would make it naturally fit in the docstring as well. To each their own, though.