Page MenuHomePhabricator

VisualEditor: Remove (and stop adding) useless documentation
Closed, ResolvedPublic

Description

/**

  • Creates an ve.Element object. *
  • @class
  • @abstract *
  • @constructor */

ve.Element = function VeElement

These and everything like are useless (not really explaining anything) and annoying (gets you excited to see a line of text only to find out its nothing) and makes the jsduck --nodoc utility unusable since a lot of things without documentation aren't without documentation.

So, henceforth, it is "okay" for a doc block to be just tags with no description on top (or even just /** */ with nothing, which is all jsduck needs to include a property in its index).

I (or someone else) will be ridding these at some point, but lets try and not duplicate them more (I won't take "consistency" as an argument here when creating something that is like something else that has a useless description, fill it in or don't copy it, don't spread the virus).

Thanks


Version: unspecified
Severity: enhancement

Details

Reference
bz51650

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 22 2014, 1:48 AM
bzimport added a project: Technical-Debt.
bzimport set Reference to bz51650.

Note that there is one (exactly one) piece of useful information in that comment: @abstract

Change 125036 had a related patch set uploaded by Krinkle:
Get rid of useless comments for classes

https://gerrit.wikimedia.org/r/125036

Change 125036 merged by jenkins-bot:
Get rid of useless comments for classes

https://gerrit.wikimedia.org/r/125036

Change 146523 had a related patch set uploaded by Krinkle:
Remove useless documentation, add more useful documentation

https://gerrit.wikimedia.org/r/146523

Change 146523 merged by jenkins-bot:
Remove useless documentation, add more useful documentation

https://gerrit.wikimedia.org/r/146523

Krinkle claimed this task.