Commit graph

10 commits

Author SHA1 Message Date
Inez Korczyński d84b02610a Minor cleanup.
Change-Id: I45ee3fd5b2131131f3d10e05a1cc2f32a3e091cc
2013-01-17 14:05:31 -08:00
Trevor Parscal 8d33a3de0d Major Documentation Cleanup
* Made method descriptions imperative: "Do this" rather than "Does this"
* Changed use of "this object" to "the object" in method documentation
* Added missing documentation
* Fixed incorrect documentation
* Fixed incorrect debug method names (as in those VeDmClassName tags we add to functions so they make sense when dumped into in the console)
* Normalized use of package names throughout
* Normalized class descriptions
* Removed incorrect @abstract tags
* Added missing @method tags
* Lots of other minor cleanup

Change-Id: I4ea66a2dd107613e2ea3a5f56ff54d675d72957e
2013-01-16 15:37:59 -08:00
Catrope a8e3b59141 Fix test breakage in 90f046799
The title attribute should only be rendered. It should not be put in the
HTML that is sent back to Parsoid.

Change-Id: I63c0373c71c3bf01a4238af3ccd02c835a118e2f
2013-01-11 20:18:09 -08:00
jenkins-bot 23ca3fcd34 Merge "Set title attributes for internal and external links." 2013-01-08 20:35:44 +00:00
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
Rob Moen 90f046799f Set title attributes for internal and external links.
Fixes (Bug 37904)

Change-Id: Ib987f74fa9f326fe583683401424c79ba9651caf
2012-12-13 14:04:00 -08:00
Trevor Parscal 42de94fc44 (bug 42298) Handle URL encoding in MWInternalLinkAnnotation
* Decode titles we get from Parsoid
* Encode titles we give to Parsoid
* Preserve the original encoded title if nothing meaningful changed (a.k.a. do not normalize unless we must)

Change-Id: If5d22e88904d6b2c438caac403ac2d78d440b017
2012-12-07 12:34:17 -08:00
Catrope fda2e6c1b5 (bug 42140) Don't force spaces to underscores in internal links
MWInternalLinkAnnotation was normalizing spaces to underscores. This is
bad. Instead, we now do the following:
* Normalize underscores to spaces for display purposes
* Store the original title without underscore/space mangling
* If the user didn't change the title (display title === original title
  with s/_/ /g), use the original title. Otherwise use the user's title
  verbatim, without normalizing either underscores or spaces.

Also, per a conversation with Gabriel, we now only restore hrefPrefix
when we're also restoring origTitle, otherwise Parsoid will barf.

Change-Id: Ia74a493b2bce96c9345b60ed692eeb2e43ebceff
2012-11-19 18:55:49 -08:00
Trevor Parscal 5cd4222d9c Whitespace and comment cleanup for dm annotation classes
* Added comments to classes and methods
* Quieted a jshint warning
* Broke some long lines
* Replaced instances of "var\t" with "var "

Change-Id: I1d617ed9e5180f1a3dff42078fb5debb5d718407
2012-10-17 12:35:28 -07:00
Catrope 613dd14332 New annotation API: convert existing annotations
This changes ve.dm.LinkAnnotation to be a generic annotation for <a>
tags, and adds ve.dm.MWInternalLinkAnnotation and
ve.dm.MWExternalLinkAnnotation as MW-specific subclasses. This nicely
splits out the MW-specific parts in LinkAnnotation, and ideally we'd
also move these files somewhere else to reflect their MW-specificity,
but I haven't gotten to that yet.

Similarly, ve.dm.TextStyleAnnotation is now a generic base class for
simple tag-only-no-metadata annotations, and it has 11 subclasses, one
for each tag we support. This is quite a bit more verbose than the
previous code, but I think it's cleaner and more flexible. I considered
writing a function that would generate a TextStyleAnnotation subclass,
then calling that 11 times, but that's not possible if we want to keep
named functions for the constructors.

Change-Id: Ifba10153eef40280e44025dd72d4e9d9f33b0632
2012-10-12 15:07:25 -07:00