Opened 10 years ago

Closed 10 years ago

Last modified 8 years ago

#14980 closed defect (fixed)

bad doc comment syntax

Reported by: Rawld Gill Owned by: Rawld Gill
Priority: high Milestone: 1.8
Component: Documentation Version: 1.7.2
Keywords: Cc:
Blocked By: Blocking:


This is a metaticket to track syntax repairs to doc comments.

Change History (17)

comment:1 Changed 10 years ago by Rawld Gill

Milestone: tbd1.8
Owner: set to Rawld Gill
Priority: undecidedhigh
Status: newassigned

comment:2 Changed 10 years ago by Rawld Gill

In [28115]:

fixed doc comment syntax errors; refs #14980; !strict

comment:3 Changed 10 years ago by Rawld Gill

Resolution: fixed
Status: assignedclosed

I'm punting doc parser project to csnover. Therefore closing this ticket.

comment:4 Changed 10 years ago by bill

In [28499]:

fix some bad doc comment syntax, refs #14980 !strict

comment:5 Changed 10 years ago by bill

In [28500]:

Remove doc comment hints about require()'d modules. They actually confuse the new doc parser rather than helping it. Refs #14980 !strict.

comment:6 Changed 10 years ago by bill

In [28504]:

Doc comment fixes for dojo/core.

1) remove unneeded doc hints about parameters of module factory functions

2) don't access dojo or declare() in doc comments if those symbols aren't defined as parameters to the factory function (i.e. if dojo/_base/kernel and dojo/_base/declare aren't listed as dependencies to the function, or if dojo/_base/kernel is loaded as kernel rather than dojo)

3) made most parameter definitions (ex: IOArgs) local variables, except for the ones defined in dojo/_base/xhr.js and dojo/number.js since they are used outside of those files

4) used native javascript to declare "classes" like IOArgs for modules where dojo/_base/declare [and dojo/lang] aren't loaded as dependencies.

Refs #14980 !strict

comment:7 Changed 10 years ago by bill

In [28512]:

Since the new doc parser is based on modules rather than globals, there's no good way to document a dojoConfig global variable.

Most of the information about dojoConfig attributes was already listed in config.rst (in our reference documentation), so I just copied the rest of the attribute information there (see and removed the dojoConfig documentation from config.js.

Refs #14980 !strict

comment:8 Changed 10 years ago by bill

In [28513]:

API doc cleanup for dojo/declare.

In order to document methods like inherited() that are available on classes created via dojo/declare, specify the return type of dojo/declare as a class with those methods. The previous doc comments documented inherited() etc. as methods on Object, which seems both inaccurate (since not all Objects have an inherited() method), and unsuitable for an AMD world, since Object is not an AMD module.

Also inlined the comments for safeMixin() etc.

Refs #14980 !strict

comment:9 Changed 10 years ago by bill

In [28514]:

Yet more API doc cleanup, refs #14980 !strict.

comment:10 Changed 10 years ago by bill

In [28515]:

Fixes to API doc for dojo/store, especially around how the store implementations conceptually extend dojo/store/api/Store (or in java terminology, implement the dojo/store/api/Store interface), and around the kwargs parameters for store methods.

Seems like the doc comments for Cache methods are redundant with api/Store doc comments, and thus can be removed, but I left them in for now.

Refs #14980 !strict.

comment:11 Changed 10 years ago by bill

In [28517]:

Fixes to API doc for dojo/dnd. Refs #14980 !strict.

comment:12 Changed 10 years ago by bill

In [28518]:

Associate API documentation with module exported functions, rather than deprecated dojo.*() functions. Refs #14980 !strict.

comment:13 Changed 10 years ago by bill

In [28520]:

Fix API doc for dijit kwargs parameters. There's a lot of inheritance going on, which requires many modules to logically export their kwarg definitions. Refs #14980 !strict.

comment:14 Changed 10 years ago by bill

In [28521]:

Prefer setObject() to getObject() since it avoids needing a doc parser hint, and since it isolates the code to set global variables (which we will remove for 2.0).

I wish we didn't have code setting global variables at all, especially since dojo.require() automatically creates a global for the module, but I suppose some user code might be using AMD syntax to require modules yet still expecting globals to be created.

Refs #14980 !strict.

comment:15 Changed 10 years ago by bill

In [28655]:

Oops, can't use setObject() here as it may overwrite, refs #14980 !strict. (I still tried to isolate the dojo global setting code, in preparation for 2.0 when we drop it.)

comment:16 Changed 10 years ago by bill

In [29444]:

fix back-compat regression from [28517] where dojo.dnd.getUniqueId() etc. stopped being defined, refs #14980 !strict

comment:17 Changed 8 years ago by bill

Partially backported to 1.7 in e7403082d02faba2e47cb645d2532dd2920f60b8.

Note: See TracTickets for help on using tickets.