Commit graph

19 commits

Author SHA1 Message Date
Timo Tijhof b11bbed7a6 JSDuck: Generated code documentation!
See CODING.md for how to run it.

Mistakes fixed:
* Warning: Unknown type function
  -> Function
* Warning: Unknown type DOMElement
  -> HTMLElement
* Warning: Unknown type DOM Node
  -> HTMLElement
* Warning: Unknown type Integer
  -> Mixed
* Warning: Unknown type Command
  -> ve.Command
* Warning: Unknown type any
  -> number
* Warning: Unknown type ve.Transaction
  -> ve.dm.Transaction
* Warning: Unknown type ve.dm.AnnotationSet
  -> ve.AnnotationSet
* Warning: Unknown type false
  -> boolean
* Warning: Unknown type ve.dm.AlienNode
  ve.dm doesn't have a generic AlienNode like ve.ce
  -> Unknown type ve.dm.AlienInlineNode|ve.dm.AlienBlockNode
* Warning: Unknown type ve.ve.Surface
  -> ve.ce.Surface
* ve.example.lookupNode:
  -> Last @param should be @return
* ve.dm.Transaction.prototype.pushReplace:
  -> @param {Array] should be @param {Array}
* Warning: ve.BranchNode.js:27: {@link ve.Node#hasChildren} links to non-existing member
  -> (removed)
* Warning: ve.LeafNode.js:21: {@link ve.Node#hasChildren} links to non-existing member
  -> (removed)

Differences fixed:
* Variadic arguments are like @param {Type...} [name]
  instead of @param {Type} [name...]
* Convert all file headers from /** to /*! because JSDuck tries
  to parse all /** blocks and fails to parse with all sorts of
   errors for "Global property", "Unnamed property", and
  "Duplicate property".
  Find: \/\*\*([^@]+)(@copyright)
  Replace: /*!$1$2
* Indented blocks are considered code examples.
  A few methods had documentation with numbered lists that were
  indented, which have now been updated to not be intended.
* The free-form text descriptions are parsed with Markdown,
  which requires lists to be separated from paragraphs by an
  empty line.
  And we should use `backticks` instead of {braces} for inline
  code in text paragraphs.
* Doc blocks for classes and their constructor have to be
  in the correct order (@constructor, @param, @return must be
  before @class, @abstract, @extends etc.)
* `@extends Class` must not have Class {wrapped}
* @throws must start with a {Type}
* @example means something else. It is used for an  inline demo
  iframe, not code block. For that simply indent with spaces.
* @member means something else.
  Non-function properties are marked with @property, not @member.
* To create a link to a class or member, in most cases the name
  is enough to create a link. E.g. Foo, Foo.bar, Foo.bar#quux,
  where a hash stands for "instance member", so Foo.bar#quux,
  links to Foo.bar.prototype.quux (the is not supported, as
  "prototype" is considered an implementation detail, it only
  indexes class name and method name).
  If the magic linker doesn't work for some case, the
  verbose syntax is {@link #target label}.
* @property can't have sub-properties (nested @param and @return
  values are supported, only @static @property can't be nested).
  We only have one case of this, which can be worked around by
  moving those in a new virtual class. The code is unaltered
  (only moved down so that it isn't with the scope of the main
  @class block). ve.dm.TransactionProcessor.processors.

New:
* @mixins: Classes mixed into the current class.
* @event: Events that can be emitted by a class. These are also
  inherited by subclasses. (+ @param, @return and @preventable).
  So ve.Node#event-attach is inherited to ve.dm.BreakNode,
  just like @method is.
* @singleton: Plain objects such as ve, ve.dm, ve.ce were missing
  documentation causing a tree error. Documented those as a
  JSDuck singleton, which they but just weren't documented yet.
  NB: Members of @singleton don't need @static (if present,
  triggers a compiler warning).
* @chainable: Shorthand for "@return this". We were using
  "@return {classname}" which is ambiguous (returns the same
  instance or another instance?), @chainable is specifically
  for "@return this". Creates proper labels in the generated
  HTML pages.

Removed:
* @mixin: (not to be confused with @mixins). Not supported by
  JSDuck. Every class is standalone anyway. Where needed marked
  them @class + @abstract instead.

Change-Id: I6a7c9e8ee8f995731bc205d666167874eb2ebe23
2013-01-05 01:16:32 +01:00
Inez Korczyński a9082e6dde Only apply HTML attributes to DOM nodes that are "safe"
* Added whitelist argument to setDomAttributes which allows filtering of attributes being set
* Added prefix argument to ve.dm.Node.getAttributes to allow extracting a subset of attributes by name prefix
* Added a whitelist to ve.ce.Node which was extracted from MediaWiki's Sanitizer class
* Replaced attribute copying code with a call to setDomAttributes using the whitelist argument, passing in attributes from a call to ve.dm.Node.getAttributes using the prefix argument

Also…

* Removed comment in constructor of ve.ce.Node, documentation for properties is usually in the getters/setters, and already was in this case
* Renamed ve.setDOMAttributes to ve.setDomAttributes
* Renamed ve.getDOMAttributes to ve.getDomAttributes
* Renamed ve.getDOMText to ve.getDomText
* Renamed ve.getDOMHash to ve.getDomHash
* Updated all callers of renamed methods

Change-Id: Id556172d5d18ea431044b9d402400e1f0e67a293
2012-11-27 14:34:29 -08:00
Timo Tijhof 1ba75b7ea9 The last ever mw.ext.ve jshint fixup
Change-Id: I262673214dd59e5bcaf4e0855e68728365b041fe
2012-11-26 22:36:07 +01:00
Catrope 6ef9fa78ff Fix ve.batchSplice() to behave in line with docs
* Actually return the spliced data like the docs claim we do
* Remove false claim that offset can be negative
* Add that data=[] && remove=0 is invalid; native splice() doesn't allow
  this, and there is a case where we call native splice() directly
* Add tests

Change-Id: I90e77c1b22ea1c36cb61e89ea47831885a0b1cb9
2012-10-30 10:05:49 -07:00
Catrope d30096ebd3 Fix copyObject/copyArray behavior with null values
Previously copyObject and copyArray would silently drop null values,
which is bad, especially considering we have example data for meta nodes
that has { 'key': null } somewhere.

Also added a test case that failed prior to this change.

Change-Id: I4f233cce041fbf38f701c494f1f78ac3d8535d88
2012-10-29 19:45:25 -07:00
Catrope 84efb81e7e Fix JS error in ve.setProp()
Attempting to descend into a string or number would cause a JS error,
because we would attempt to create prop[arguments[i]] as an empty object
(which is ignored), then try to descend into it (which blows up because
it's undefined, even though we've just set it). Guard against this by
explicitly checking for non-object-ness.

Change-Id: Ie65550baaae0ab88476c9a1ff40cc136090740a0
2012-10-25 21:54:45 +02:00
Catrope cc9c530690 Add ve.setProp()
Change-Id: I6f932917f8e6321e9c415900b70404406af96d5c
2012-10-19 11:22:12 -07:00
Trevor Parscal 2a1eb1394d Merge "Add ve.getProp()" 2012-10-11 18:26:31 +00:00
Trevor Parscal 9b7f9cda42 Merge "Add ve.getOpeningHtmlTag()" 2012-10-11 18:16:55 +00:00
Trevor Parscal f72083f85c Merge "Add setDOMAttributes()" 2012-10-11 18:16:13 +00:00
Catrope a7a64abcf5 Add ve.getProp()
Change-Id: Iad9f53ae252acbeb2842645e6e66c0dfc7618f9f
2012-10-10 17:50:19 -07:00
Catrope 22c7f16b99 Add ve.getOpeningHtmlTag()
Utility function to generate an opening HTML tag. Needed to integrate
the new annotation API with ve.ce.TextNode

Change-Id: I6804bbf6f79346fde1887fa82d29ec5cd0342d60
2012-10-10 17:30:07 -07:00
Catrope 3f4c656275 Add setDOMAttributes()
Change-Id: I1406998400c4f7f3d0983a43e3f86afe4ffd29a6
2012-10-10 15:10:31 -07:00
Timo Tijhof 07c86fc5d3 inheritClass: Implement inherited 'static' property for classes.
Previously tests for inheritClass (and other object management
utilities) were absent (as they were copied from upstream K-js).

I've copied the upstream test suite for this method here and
extended it with tests for this new feature.

Had to add es5:true to .jshintrc due to a bug in JSHint.
Repeated the setting in ve.inheritClass for future reference.

Source: https://github.com/Krinkle/K-js/blob/master/test/K.test.js

Change-Id: I63ac620d6ce7832ebfee454ddf7b7c90f6eb6121
2012-10-09 18:29:41 +00:00
Trevor Parscal 944228aec7 Whitespace and comments
* Added documentation for ve.AnnotationSet
* Replaced uses of "// Inheritance" with "// parent Constructor"
* Added "// Mixin constructor" where needed
* Added missing section comments like "/* Static Methods */"
* Cleaned up excessive newlines (matching /\n\n\n/g)
* Put unnecessarily multi-line statements on a single line

Change-Id: I2c9b47ba296f7dd3c9cc2985581fbcefd6d76325
2012-09-17 16:53:03 -07:00
Timo Tijhof ab7d6bf082 Documentation & clean up
* Commands for Sublime:

  Find*: "(\* @[a-z]+) ([^{].*) \{(.*)\}"
  Replace: "$1 {$3} $2"

  Save all && Close all

  Find: " function("
  Replace: " function ("

  Save all && Close all

  Find: "Intialization"
  Replace: "Initialization"

  Save all && Close all

* Consistent use of types (documented in CODING.rm):
  - Merged {Integer} into {Number}.
  - Merged {DOM Node} into {DOMElement}.

* Remove work-around /*jshint newcap: false */ from ve.js
  Calling Object() as a function to to use the internal
  toObject no longer throws a newcap warning in JSHint.
  It only does that normal functions now .

  (e.g. var a = Cap(); or var a = new uncap();)

* Add missing annotations (@static, @method, ..).

* Remove unused variables

* Remove null-assignments to variables that should just be
  undefined. There's a few variables explicitly set to null
  whereas they are set a few lines under and not used otherwise
  (e.g. 'tx' in ve.ce.Surface.prototype.onPaste)

Change-Id: I0721a08f8ecd93c25595aedaa1aadb0e08b83799
2012-09-17 16:02:52 +02:00
Catrope debc429a9f Also add clone functionality, undefined guard and tests to ve.copyObject()
Change-Id: I84ca938cbedf93bfd1c73da16bf9d0d96b3bc749
2012-09-06 14:52:41 -07:00
Catrope da1d0d4391 Fix error in ve.copyArray() and add tests
Change-Id: I05e7971d05dfa3118db97d76f51985f64d994d8b
2012-09-05 00:26:10 +02:00
Timo Tijhof c8ed44fb07 Refactor ve.getHash: Stabilize cross-browser differences; + unit tests
* Replaces c8b4a28936

* Use Object() casting to detect objects instead of .constructor
  (or instanceof). Both .constructor and instanceof compare by reference
  the type "Object" which means if the object comes from another window
  (where there is a different "Object" and "Object.prototype") it will
  drop out of the system and go freewack.

  Theory: If a variable casted to an object returns true when strictly compared
  to the original, the input must be an object.

  Which is true. It doesn't change the inheritance, it doesn't make it inherit
  from this window's Object if the object is from another window's object. All it
  does is cast to an object if not an object already.
  So e.g. "Object(5) !== 5" because 5 is a primitive value as opposed to an instance
  of Number.
  And contrary to "typeof", it doesn't return true for "null".

* .constructor also has the problem that it only works this way if the
  input is a plain object. e.g. a simple construtor function that creates
  an object also get in the wrong side of the if/else case since it is
  an instance of Object, but not directly (rather indirectly via another
  constructor).

* Added unit tests for basic getHash usage, as well as regression tests
  against the above two mentioned problems (these tests fail before this commit).

* While at it, also improved other utilities a bit.
 - Use hasOwnProperty instead of casting to boolean
   when checking for presence of native support.
   Thanks to Douglas Crockford for that tip.
 - Fix documentation for ve.getHash: Parameter is not named "obj".
 - Add Object-check to ve.getObjectKeys per ES5 Object.keys spec (to match native behavior)
 - Add Object-check to ve.getObjectValues to match ve.getObjectKeys
 - Improved performance of ve.getObjectKeys shim. Tried several potential optimizations
   and compared with jsperf. Using a "static" reference to hasOwn improves performance
   (by not having to look it up 4 scopes up and 3 property levels deep).
   Also using [.length] instead of .push() shared off a few ms.
 - Added unit tests for ve.getObjectValues

Change-Id: If24d09405321f201c67f7df75d332bb1171c8a36
2012-08-27 00:14:02 +02:00