Make dojo core module summaries show up in the doc.

This mainly involved moving summaries from the top (ie, the callback method to define()) to the object returned by the module.   Or, if the information was duplicated in both places, then just removing the module level info.

There were some cases where I had to introduce faux return values from methods (ex: NodeList-data.js).   Also, I moved a few summaries from a constructor method to the top of the object.

A few modules were impossible to fix:
   - dom-attr, dom-construct, dom-prop: due to the use of exports
   - on, has - because the summary for the function on() is different than the summary for the module containing on() and the other functions hanging off of on.
   - dojo/main - returns the dojo/_base/kernel object but the summary is importantly different: it should say that dojo/main forces all the dojo/_base modules to be loaded
 
Also fixed various API doc formatting errors,and some spacing errors.

Refs #13101 !strict.



git-svn-id: http://svn.dojotoolkit.org/src/dojo/trunk@28901 560b804f-0ae3-0310-86f3-f6aa0a117693

AdapterRegistry.js

@@ -1,8 +1,6 @@
-define(["./_base/kernel", "./_base/lang"], function(dojo, lang) {
-	// module:
-	//		dojo/AdapterRegistry
-	// summary:
-	//		TODOC
+define(["./_base/kernel", "./_base/lang"], function(dojo, lang){
+// module:
+//		dojo/AdapterRegistry
 
 var AdapterRegistry = dojo.AdapterRegistry = function(/*Boolean?*/ returnWrappers){
 	// summary:

Deferred.js

@@ -7,8 +7,6 @@ define([
 
 	// module:
 	//		dojo/Deferred
-	// summary:
-	//		Deferred base class.
 
 	var PROGRESS = 0,
 			RESOLVED = 1,
@@ -75,7 +73,6 @@ define([
 		//		Constructor for a deferred.
 		// description:
 		//		Creates a new Deferred. This API is preferred over dojo/_base/Deferred.
-		//
 		// canceler:
 		//		Will be invoked if the deferred is canceled. The canceler receives the
 		//		reason the deferred was canceled as its argument. The deferred is
@@ -182,7 +179,6 @@ define([
 			//		Add new callbacks to the deferred.
 			// returns: dojo/promise/Promise
 			//		Returns a new promise for the result of the callback(s).
-			//
 			// callback:
 			//		Callback to be invoked when the promise is resolved.
 			// errback:
@@ -226,7 +222,6 @@ define([
 			//		promise. Can affect other promises that originate with the same
 			//		deferred. Returns the rejection reason if the deferred was canceled
 			//		normally.
-			//
 			// reason:
 			//		A message that may be sent to the deferred's canceler, explaining why
 			//		it's being canceled.

DeferredList.js

@@ -1,8 +1,6 @@
-define(["./_base/kernel", "./_base/Deferred", "./_base/array"], function(dojo, Deferred, darray) {
+define(["./_base/kernel", "./_base/Deferred", "./_base/array"], function(dojo, Deferred, darray){
 	// module:
 	//		dojo/DeferredList
-	// summary:
-	//		TODOC
 
 
 dojo.DeferredList = function(/*Array*/ list, /*Boolean?*/ fireOnOneCallback, /*Boolean?*/ fireOnOneErrback, /*Boolean?*/ consumeErrors, /*Function?*/ canceller){
@@ -13,7 +11,6 @@ dojo.DeferredList = function(/*Array*/ list, /*Boolean?*/ fireOnOneCallback, /*B
 	//		this new deferred will typically have its callback fired when all of the deferreds in
 	//		the given list have fired their own deferreds.  The parameters `fireOnOneCallback` and
 	//		fireOnOneErrback, will fire before all the deferreds as appropriate
-	//
 	// list:
 	//		The list of deferreds to be synchronizied with this DeferredList
 	// fireOnOneCallback:

Evented.js

@@ -1,23 +1,23 @@
 define(["./aspect", "./on"], function(aspect, on){
 	// module:
 	//		dojo/Evented
-	// summary:
-	//		The export of this module is a class that can be used as a mixin or base class, 
-	// 		to add on() and emit() methods to a class
-	// 		for listening for events and emitting events:
-	//
-	// 		|	define(["dojo/Evented"], function(Evented){
-	// 		|		var EventedWidget = dojo.declare([Evented, dijit._Widget], {...});
-	//		|		widget = new EventedWidget();
-	//		|		widget.on("open", function(event){
-	//		|		... do something with event
-	//		|	 });
-	//		|
-	//		|	widget.emit("open", {name:"some event", ...});
 
  	"use strict";
  	var after = aspect.after;
 	function Evented(){
+		// summary:
+		//		A class that can be used as a mixin or base class,
+		// 		to add on() and emit() methods to a class
+		// 		for listening for events and emitting events:
+		//
+		// 		|	define(["dojo/Evented"], function(Evented){
+		// 		|		var EventedWidget = dojo.declare([Evented, dijit._Widget], {...});
+		//		|		widget = new EventedWidget();
+		//		|		widget.on("open", function(event){
+		//		|		... do something with event
+		//		|	 });
+		//		|
+		//		|	widget.emit("open", {name:"some event", ...});
 	}
 	Evented.prototype = {
 		on: function(type, listener){

NodeList-data.js

@@ -1,72 +1,18 @@
 define([
 	"./_base/kernel", "./query", "./_base/lang", "./_base/array", "./dom-attr"
-], function(dojo, query, lang, array, attr) {
+], function(dojo, query, lang, array, attr){
 	// module:
 	//		dojo/NodeList-data
-	// summary:
-	//		TODOC
 
-	var NodeList = query.NodeList;
 /*=====
-
-	NodeList.prototype.data = function(key, value){
-		// summary: stash or get some arbitrary data on/from these nodes.
-		//
-		// description:
-		//		Stash or get some arbitrary data on/from these nodes. This private _data function is
-		//		exposed publicly on `dojo.NodeList`, eg: as the result of a `dojo.query` call.
-		//		DIFFERS from jQuery.data in that when used as a getter, the entire list is ALWAYS
-		//		returned. EVEN WHEN THE LIST IS length == 1.
-		//
-		//		A single-node version of this function is provided as `dojo._nodeData`, which follows
-		//		the same signature, though expects a String ID or DomNode reference in the first
-		//		position, before key/value arguments.
-		//
-		// node: String|DomNode
-		//		The node to associate data with
-		//
-		// key: Object|String?
-		//		If an object, act as a setter and iterate over said object setting data items as defined.
-		//		If a string, and `value` present, set the data for defined `key` to `value`
-		//		If a string, and `value` absent, act as a getter, returning the data associated with said `key`
-		//
-		// value: Anything?
-		//		The value to set for said `key`, provided `key` is a string (and not an object)
-		//
-		// example:
-		//		Set a key `bar` to some data, then retrieve it.
-		//	|	dojo.query(".foo").data("bar", "touched");
-		//	|	var touched = dojo.query(".foo").data("bar");
-		//	|	if(touched[0] == "touched"){ alert('win'); }
-		//
-		// example:
-		//		Get all the data items for a given node.
-		//	|	var list = dojo.query(".foo").data();
-		//	|	var first = list[0];
-		//
-		// example:
-		//		Set the data to a complex hash. Overwrites existing keys with new value
-		//	|	dojo.query(".foo").data({ bar:"baz", foo:"bar" });
-		//		Then get some random key:
-		//	|	dojo.query(".foo").data("foo"); // returns [`bar`]
-		//
-		//	returns: Object|Anything|Nothing
-		//		When used as a setter via `dojo.NodeList`, a NodeList instance is returned
-		//		for further chaning. When used as a getter via `dojo.NodeList` an ARRAY
-		//		of items is returned. The items in the array correspond to the elements
-		//		in the original list. This is true even when the list length is 1, eg:
-		//		when looking up a node by ID (#foo)
-	};
-
-	NodeList.prototype.removeData = function(key){
-		// summary: Remove the data associated with these nodes.
-		// key: String?
-		//		If ommitted, clean all data for this node.
-		//		If passed, remove the data item found at `key`
-	};
-
+return function(){
+	// summary:
+	//		Adds data() and removeData() methods to NodeList, and returns NodeList constructor.
+};
 =====*/
 
+	var NodeList = query.NodeList;
+
 	var dataCache = {}, x = 0, dataattr = "data-dojo-dataid",
 		dopid = function(node){
 			// summary: Return a uniqueish ID for the passed node reference
@@ -87,7 +33,8 @@ define([
 	//>>excludeEnd("debugging");
 
 	var dodata = dojo._nodeData = function(node, key, value){
-		// summary: Private helper for dojo.NodeList.data for single node data access. Refer to NodeList.data 
+		// summary:
+		//		Private helper for dojo.NodeList.data for single node data access. Refer to NodeList.data
 		//		documentation for more information.
 		//
 		// node: String|DomNode
@@ -123,7 +70,8 @@ define([
 	};
 
 	var removeData = dojo._removeNodeData = function(node, key){
-		// summary: Remove some data from this node
+		// summary:
+		//		Remove some data from this node
 		// node: String|DomNode
 		//		The node reference to remove data from
 		// key: String?
@@ -140,7 +88,8 @@ define([
 	};
 
 	dojo._gcNodeData = function(){
-		// summary: super expensive: GC all data in the data for nodes that no longer exist in the dom.
+		// summary:
+		//		super expensive: GC all data in the data for nodes that no longer exist in the dom.
 		// description:
 		//		super expensive: GC all data in the data for nodes that no longer exist in the dom.
 		//		MUCH safer to do this yourself, manually, on a per-node basis (via `NodeList.removeData()`)
@@ -162,6 +111,68 @@ define([
 		removeData: NodeList._adaptAsForEach(removeData)
 	});
 
+	/*=====
+	 lang.extend(NodeList, {
+		 data: function(key, value){
+			 // summary:
+			 //		stash or get some arbitrary data on/from these nodes.
+			 //
+			 // description:
+			 //		Stash or get some arbitrary data on/from these nodes. This private _data function is
+			 //		exposed publicly on `dojo.NodeList`, eg: as the result of a `dojo.query` call.
+			 //		DIFFERS from jQuery.data in that when used as a getter, the entire list is ALWAYS
+			 //		returned. EVEN WHEN THE LIST IS length == 1.
+			 //
+			 //		A single-node version of this function is provided as `dojo._nodeData`, which follows
+			 //		the same signature, though expects a String ID or DomNode reference in the first
+			 //		position, before key/value arguments.
+			 //
+			 // node: String|DomNode
+			 //		The node to associate data with
+			 //
+			 // key: Object|String?
+			 //		If an object, act as a setter and iterate over said object setting data items as defined.
+			 //		If a string, and `value` present, set the data for defined `key` to `value`
+			 //		If a string, and `value` absent, act as a getter, returning the data associated with said `key`
+			 //
+			 // value: Anything?
+			 //		The value to set for said `key`, provided `key` is a string (and not an object)
+			 //
+			 // example:
+			 //		Set a key `bar` to some data, then retrieve it.
+			 //	|	dojo.query(".foo").data("bar", "touched");
+			 //	|	var touched = dojo.query(".foo").data("bar");
+			 //	|	if(touched[0] == "touched"){ alert('win'); }
+			 //
+			 // example:
+			 //		Get all the data items for a given node.
+			 //	|	var list = dojo.query(".foo").data();
+			 //	|	var first = list[0];
+			 //
+			 // example:
+			 //		Set the data to a complex hash. Overwrites existing keys with new value
+			 //	|	dojo.query(".foo").data({ bar:"baz", foo:"bar" });
+			 //		Then get some random key:
+			 //	|	dojo.query(".foo").data("foo"); // returns [`bar`]
+			 //
+			 // returns: Object|Anything|Nothing
+			 //		When used as a setter via `dojo.NodeList`, a NodeList instance is returned
+			 //		for further chaining. When used as a getter via `dojo.NodeList` an ARRAY
+			 //		of items is returned. The items in the array correspond to the elements
+			 //		in the original list. This is true even when the list length is 1, eg:
+			 //		when looking up a node by ID (#foo)
+		 },
+
+		 removeData: function(key){
+			 // summary:
+			 //		Remove the data associated with these nodes.
+			 // key: String?
+			 //		If omitted, clean all data for this node.
+			 //		If passed, remove the data item found at `key`
+		 }
+	 });
+	 =====*/
+
 // TODO: this is the basic implementation of adaptWithCondtionAndWhenMappedConsiderLength, for lack of a better API name
 // it conflicts with the the `dojo.NodeList` way: always always return an arrayLike thinger. Consider for 2.0:
 //

NodeList-dom.js

@@ -1,4 +1,15 @@
 define(["./_base/kernel", "./query", "./_base/array", "./_base/lang", "./dom-class", "./dom-construct", "./dom-geometry", "./dom-attr", "./dom-style"], function(dojo, query, array, lang, domCls, domCtr, domGeom, domAttr, domStyle){
+
+	// module:
+	//		dojo/NodeList-dom.js
+
+	/*=====
+	 return function(){
+		 // summary:
+		 //		Adds DOM related methods to NodeList, and returns NodeList constructor.
+	 };
+	 =====*/
+
 	var magicGuard = function(a){
 		// summary:
 		//		the guard function for dojo.attr() and dojo.style()

NodeList-fx.js

@@ -1,11 +1,15 @@
 define(["./_base/NodeList", "./_base/lang", "./_base/connect", "./_base/fx", "./fx"],
-  function(NodeList, lang, connectLib, baseFx, coreFx) {
+  function(NodeList, lang, connectLib, baseFx, coreFx){
 	// module:
 	//		dojo/NodeList-fx
+
+/*=====
+return function(){
 	// summary:
 	//		Adds dojo.fx animation support to dojo.query() by extending the NodeList class
 	//		with additional FX functions.  NodeList is the array-like object used to hold query results.
-
+};
+=====*/
 
 lang.extend(NodeList, {
 	_anim: function(obj, method, args){

NodeList-html.js

@@ -1,8 +1,14 @@
-define(["./query", "./_base/lang", "./html"], function(query, lang, html) {
-	// module:
-	//		dojo/NodeList-html
+define(["./query", "./_base/lang", "./html"], function(query, lang, html){
+
+// module:
+//		dojo/NodeList-html
+
+/*=====
+return function(){
 	// summary:
 	//		Adds a chainable html method to dojo.query() / NodeList instances for setting/replacing node content
+};
+=====*/
 
 var NodeList = query.NodeList;
 

NodeList-manipulate.js

@@ -1,9 +1,14 @@
-define(["./query", "./_base/lang", "./_base/array", "./dom-construct", "./NodeList-dom"], function(dquery, lang, array, construct) {
+define(["./query", "./_base/lang", "./_base/array", "./dom-construct", "./NodeList-dom"], function(dquery, lang, array, construct){
 	// module:
 	//		dojo/NodeList-manipulate
-	// summary:
-	//		Adds chainable methods to dojo.query() / Nodelist instances for manipulating HTML
-	//		and DOM nodes and their properties.
+
+	/*=====
+	return function(){
+		// summary:
+		//		Adds chainable methods to dojo.query() / NodeList instances for manipulating HTML
+		//		and DOM nodes and their properties.
+	};
+	=====*/
 
 	var NodeList = dquery.NodeList;
 

NodeList-traverse.js

@@ -1,8 +1,13 @@
-define(["./query", "./_base/lang", "./_base/array"], function(dquery, lang, array) {
+define(["./query", "./_base/lang", "./_base/array"], function(dquery, lang, array){
 	// module:
 	//		dojo/NodeList-traverse
+
+/*=====
+return function(){
 	// summary:
-	//		Adds chainable methods to dojo.query() / Nodelist instances for traversing the DOM
+	//		Adds chainable methods to dojo.query() / NodeList instances for traversing the DOM
+};
+=====*/
 
 var NodeList = dquery.NodeList;
 

OpenAjax.js

@@ -173,7 +173,7 @@ if(!window["OpenAjax"]){
 		// The following function is provided for automatic testing purposes.
 		// It is not expected to be deployed in run-time OpenAjax Hub implementations.
 		h.reinit = function(){
-			for (var lib in OpenAjax.hub.libraries) {
+			for (var lib in OpenAjax.hub.libraries){
 				delete OpenAjax.hub.libraries[lib];
 			}
 			OpenAjax.hub.registerLibrary("OpenAjax", "http://openajax.org/hub", "0.6", {});

Stateful.js

@@ -1,9 +1,6 @@
-define(["./_base/declare", "./_base/lang", "./_base/array", "dojo/when"], function(declare, lang, array, when) {
+define(["./_base/declare", "./_base/lang", "./_base/array", "dojo/when"], function(declare, lang, array, when){
 	// module:
 	//		dojo/Stateful
-	// summary:
-	//		A module that provides the base class for objects that provide named properties
-	//		with auto-magic accessors and the ability to watch for property changes
 
 return declare("dojo.Stateful", null, {
 	// summary: