Opened 5 years ago

Closed 13 months ago

#9871 closed defect (fixed)

dojox.drawing inline docs break doc parsing

Reported by: dante Owned by: mwilcox
Priority: low Milestone: 1.9
Component: Documentation Version: 1.3.2
Keywords: Cc:
Blocked by: Blocking:

Description (last modified by dante)

There is a pseudo-doc block in dojox/drawing/manager/Canvas.js (line 89ish) that is improperly formatted. Didn't see where the __CanvasArgs psuedodoc is used, but the function signature is wrong and the commented section isn't valid JS (thus breaking parsing).

Removing the offending block allows parser past, but I am sure the intent was to document _something_ within that file so it should be addressed.

Technically a blocker as the parser won't gracefully ignore the offending block. Only assigning to mwilcox because svn blame lists him as the primary dev.

Change History (10)

comment:1 Changed 5 years ago by dante

  • Description modified (diff)

comment:2 Changed 5 years ago by dante

Additionally, there is an error in dojox/drawing/stencil/Ellipse.js ... StencilData is used, but the following Array is not. It seems the formatting is wrong in StencilData as well (no actual object members defined) but I won't know until the parser makes it all the way through.

comment:3 Changed 5 years ago by dante

actually, about 6 files have the same issue (improper formatting on the stencilArgs bit). This can be easily located by running from a webbrowser util/docscripts/_browse2.php and selecting the file whose inline docs you wish to inspect (hint: you get a fatal error with debugging text pointing to the precise line number where the error happens).

I'm going to checkin what changes I did make to get the parser running, but this dojox package needs to be updated properly if it is to go beyond experimental

comment:4 Changed 5 years ago by dante

(In [20082]) refs #9871 - moving inline docs around to allow parser to pass by without fatal error. leaving as blocker/open so my changes go noticed. Getting \!strict warnings, too

comment:5 Changed 5 years ago by mwilcox

  • Milestone changed from 1.4 to future

comment:6 Changed 13 months ago by dylan

  • Milestone changed from future to 1.9
  • Priority changed from high to low

doc parser errors were resolved for 1.8.

The inline docs still show pre-AMD usage. Does dojox/drawing work using "pure AMD" syntax?

comment:7 Changed 13 months ago by bill

Sounds like you should close the ticket as fixed in 1.8. http://livedocs.dojotoolkit.org/dojox/drawing shows an example using AMD but not sure if that's what you mean; it's declarative, so it isn't using the return values from the AMD modules.

comment:8 Changed 13 months ago by dylan

The inline docs still show pre-AMD syntax, pre data-dojo-type syntax, see http://dojotoolkit.org/api/1.8/dojox/drawing/Drawing for example, things like dijit.byId('myDrawing').

I thought about updating it, but I wasn't sure if

<div dojoType="dojox.drawing.Drawing" id="drawing" defaults="myCustom.defaults"
plugins="[{'name':'dojox.drawing.plugins.drawing.Grid', 'options':{gap:100}}]">

could safely be replaced by:

<div data-dojo-type="dojox/drawing/Drawing" id="drawing" 
data-dojo-props="defaults:myCustom.defaults, 
plugins: [{'name':'dojox.drawing.plugins.drawing.Grid', 'options':{gap:100}}]">

for example.

comment:9 Changed 13 months ago by bill

I see. Theoretically the change would be transparent to dojox/drawing as the parser would handle it. If it were up to me I'd just rip out all those examples anyway. They should be in the reference doc, not the API doc, to avoid repitition.

comment:10 Changed 13 months ago by dylan

  • Resolution set to fixed
  • Status changed from new to closed

In [31143]:

fixes #9871, very minor inline documentation fixes for dojox/drawing... would prefer the clean this up more, but really to do that would be to make sure this module is completely converted to modern dojo practices, which is not the case, !strict

Note: See TracTickets for help on using tickets.