Opened 13 years ago

Closed 9 years ago

#9871 closed defect (fixed)

dojox.drawing inline docs break doc parsing

Reported by: dante Owned by: Mike Wilcox
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 13 years ago by dante

Description: modified (diff)

comment:2 Changed 13 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 13 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 13 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 13 years ago by Mike Wilcox

Milestone: 1.4future

comment:6 Changed 9 years ago by dylan

Milestone: future1.9
Priority: highlow

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 9 years ago by bill

Sounds like you should close the ticket as fixed in 1.8. 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 9 years ago by dylan

The inline docs still show pre-AMD syntax, pre data-dojo-type syntax, see 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" 
plugins: [{'name':'dojox.drawing.plugins.drawing.Grid', 'options':{gap:100}}]">

for example.

comment:9 Changed 9 years 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 9 years ago by dylan

Resolution: fixed
Status: newclosed

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.