Opened 8 years ago

Closed 8 years ago

Last modified 5 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:

Description

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

Change History (17)

comment:1 Changed 8 years ago by Rawld Gill

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

comment:2 Changed 8 years ago by Rawld Gill

In [28115]:

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

comment:3 Changed 8 years ago by Rawld Gill

Resolution: fixed
Status: assignedclosed

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

comment:4 Changed 8 years ago by bill

In [28499]:

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

comment:5 Changed 8 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 8 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 8 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 https://github.com/dojo/docs/commit/ed817fb09272267088d32de23ba98ab79705b72e) and removed the dojoConfig documentation from config.js.

Refs #14980 !strict

comment:8 Changed 8 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 8 years ago by bill

In [28514]:

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

comment:10 Changed 8 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 8 years ago by bill

In [28517]:

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

comment:12 Changed 8 years ago by bill

In [28518]:

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

comment:13 Changed 8 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 8 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 7 years ago by bill

In [28655]:

Oops, can't use setObject() here as it may overwrite dojo.data.stamp, 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 7 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 5 years ago by bill

Partially backported to 1.7 in e7403082d02faba2e47cb645d2532dd2920f60b8.

Note: See TracTickets for help on using tickets.