Merge branch 'friendly-err-sys' of https://github.com/processing/p5.js into friendly-err-sys

Author: almchung

.gitignore

@@ -4,10 +4,11 @@ node_modules/*
 experiments/*
 lib_old/*
 lib/p5.*
+lib/modules
 lib/addons/p5.dom.min.js
 docs/reference/*
 docs/yuidoc-p5-theme/assets/js/reference.js*
 !*.gitkeep
 examples/3d/
 .idea
-.vscode
+.vscode

Gruntfile.js

@@ -61,7 +61,6 @@ function getYuidocOptions() {
       helpers: [],
       preprocessor: './docs/preprocessor.js',
       outdir: 'docs/reference/'
-      //, quiet: false
     }
   };
 
@@ -92,6 +91,7 @@ module.exports = function(grunt) {
 
     // read in the package, used for knowing the current version, et al.
     pkg: grunt.file.readJSON('package.json'),
+
     // Configure style consistency checking for this file, the source, and the tests.
     jscs: {
       options: {
@@ -214,18 +214,20 @@ module.exports = function(grunt) {
           logErrors: true,
           timeout: 100000
         }
-      },
+      }
     },
 
     // This is a standalone task, used to automatically update the bower.json
-    // file to match the values in package.json.   It is (likely) used as part
+    // file to match the values in package.json. It is (likely) used as part
     // of the manual release strategy.
     update_json: {
+
       // set some task-level options
       options: {
         src: 'package.json',
         indent: '\t'
       },
+
       // update bower.json with data from package.json
       bower: {
         src: 'package.json', // where to read from
@@ -235,12 +237,9 @@ module.exports = function(grunt) {
       }
     },
 
-    // The actual compile step:  This should collect all the dependencies
-    // and compile them into a single file.
+    // This generates the theme for the documentation from the theme source
+    // files.
     requirejs: {
-
-      // This generates the theme for the documentation from the theme source
-      // files.
       yuidoc_theme: {
         options: {
           baseUrl: './docs/yuidoc-p5-theme-src/scripts/',
@@ -297,6 +296,7 @@ module.exports = function(grunt) {
         }
       }
     },
+
     // This is a static server which is used when testing connectivity for the
     // p5 library. This avoids needing an internet connection to run the tests.
     // It serves all the files in the test directory at http://localhost:9001/
@@ -343,7 +343,13 @@ module.exports = function(grunt) {
     }
   });
 
-  // Load task definitions
+  // Load build tasks.
+  // This contains the complete build task ("browserify")
+  // and the task to generate user select modules of p5
+  // ("combineModules") which can be invoked directly by
+  // `grunt combineModules:module_1:module_2` where core
+  // is included by default in all combinations always.
+  // NOTE: "module_x" is the name of it's folder in /src.
   grunt.loadTasks('build/tasks');
 
   // Load the external libraries used.
@@ -363,7 +369,6 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-minjson');
 
   // Create the multitasks.
-  // TODO: "requirejs" is in here to run the "yuidoc_themes" subtask. Is this needed?
   grunt.registerTask('build', ['browserify', 'uglify', 'requirejs']);
   grunt.registerTask('test', ['jshint', 'jscs', 'build', 'yuidoc:dev', 'connect', 'mocha', 'mochaTest']);
   grunt.registerTask('test:nobuild', ['jshint:test', 'jscs:test', 'connect', 'mocha']);

README.md

@@ -14,7 +14,7 @@ If you have found a bug in the p5.js library, you can file it here under the [
 
 ## p5.js library
 
-To use p5.js, you can [download the p5.js library here](http://p5js.org/download).  If you are interested in the most recent, less stable version, you can clone this repository and run `grunt` from the command line to generate the library from source. See the [development](https://github.com/processing/p5.js/wiki/Development) wiki for more information about our build process.
+To use p5.js, you can [download the p5.js library here](http://p5js.org/download). If you are interested in the most recent, less stable version, you can clone this repository and run `grunt` from the command line to generate the library from source. See the [development](https://github.com/processing/p5.js/wiki/Development) wiki for more information about our build process.
 
 ## Issues
 
@@ -23,12 +23,12 @@ Please post bugs in the proper repository:
 * p5.js general and p5.dom: [https://github.com/processing/p5.js/issues](https://github.com/processing/p5.js/issues)
 * p5.sound: [https://github.com/processing/p5.js-sound/issues](https://github.com/processing/p5.js-sound/issues)
 * p5.js website: [https://github.com/processing/p5.js-website/issues](https://github.com/processing/p5.js-website/issues)
-* p5.js web editor: [https://github.com/processing/p5.js-website/issues](https://github.com/processing/p5.js-web-editor/issues)
+* p5.js web editor: [https://github.com/processing/p5.js-web-editor/issues](https://github.com/processing/p5.js-web-editor/issues)
 
 
 ## Learning
 
-Check out [p5js.org](http://p5js.org) for lots more! Here are some quicklinks:
+Check out [p5js.org](http://p5js.org) for lots more! Here are some quick-links:
 
 * [Get Started](http://p5js.org/get-started) — Create and run your first sketch!
 * [p5.js overview](https://github.com/processing/p5.js/wiki/p5.js-overview) — An overview of the main features and functionality of p5.js.
@@ -43,7 +43,3 @@ Check out [p5js.org](http://p5js.org) for lots more! Here are some quicklinks:
 p5.js is a collaborative project created by many individuals, and you are invited to help. All types of involvement are welcome. See the [community section](http://p5js.org/community) to get started!
 
 Developers, check out the [development](https://github.com/processing/p5.js/wiki/Development) wiki page for more in-depth details about contributing code, bug fixes, and documentation.
-
-
-
-

build/tasks/combineModules.js

@@ -0,0 +1,77 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var browserify = require('browserify');
+var derequire = require('derequire');
+
+module.exports = function(grunt) {
+
+  grunt.registerTask('combineModules', 'Compile and combine certain modules with Browserify', function(args) {
+    // Reading and writing files is asynchronous
+    var done = this.async();
+
+    // Module sources are space separated names in a single string (enter within quotes)
+    var module_src, temp = [];
+    for (var i in arguments) {
+      temp.push(arguments[i]);
+    }
+    module_src = temp.join(', ');
+
+    // Render the banner for the top of the file. Includes the Module name.
+    var bannerTemplate = '/*! Custom p5.js v<%= pkg.version %> <%= grunt.template.today("mmmm dd, yyyy") %> \nContains the following modules : ' + module_src + '*/';
+    var banner = grunt.template.process(bannerTemplate);
+
+    // Make a list of sources from app.js in that sequence only
+    var sources = [];
+    var dump = fs.readFileSync('./src/app.js', 'utf8');
+    var regexp = /\(\'.+\'/g;
+    var match;
+    while( (match = regexp.exec(dump)) != null) {
+      var text = match[0];
+      text = text.substring(text.indexOf('./')+2, text.length-1);
+      sources.push(text);
+    }
+
+    // Populate the source file path array with concerned files' path
+    var srcDirPath = './src';
+    var srcFilePath = [];
+    for (var j = 0; j < sources.length; j++) {
+      var source = sources[j];
+      var base = source.substring(0,source.lastIndexOf('/'));
+      if(base === 'core' || module_src.search(base) !== -1) {
+        // Push the resolved paths directly
+        var filePath = (source.search('.js') !== -1) ? source : source + '.js';
+        var fullPath = path.resolve(srcDirPath, filePath);
+        srcFilePath.push(fullPath);
+      }
+    }
+
+    console.log(srcFilePath);
+    // Target file path
+    var libFilePath = path.resolve('lib/modules/p5Custom.js');
+
+    // Invoke Browserify programatically to bundle the code
+    var bundle = browserify(srcFilePath, {
+        standalone: 'p5'
+      })
+      .transform('brfs')
+      .bundle();
+
+    // Start the generated output with the banner comment,
+    var code = banner + '\n';
+
+    // Then read the bundle into memory so we can run it through derequire
+    bundle.on('data', function(data) {
+      code += data;
+    }).on('end', function() {
+      grunt.file.write(libFilePath, derequire(code));
+
+      // Print a success message
+      grunt.log.writeln('>>'.green + ' Module ' + libFilePath.blue + ' created.');
+
+      // Complete the task
+      done();
+    });
+  });
+};

docs/preprocessor.js

@@ -73,17 +73,27 @@ function mergeOverloadedMethods(data) {
         assertEqual(classitem.description || '', '',
                     'additional overloads should have no description');
 
-        if (!method.overloads) {
-          method.overloads = [{
+        function makeOverload(method) {
+          var overload = {
             line: method.line,
-            params: processOverloadedParams(method.params)
-          }];
+            params: processOverloadedParams(method.params || [])
+          };
+          // TODO: the doc renderer assumes (incorrectly) that
+          //   these are the same for all overrides
+          if (method.static)
+            overload.static = method.static;
+          if (method.chainable)
+            overload.chainable = method.chainable;
+          if (method.return)
+            overload.return = method.return;
+          return overload;
+        }
+
+        if (!method.overloads) {
+          method.overloads = [makeOverload(method)];
           delete method.params;
         }
-        method.overloads.push({
-          line: classitem.line,
-          params: processOverloadedParams(classitem.params)
-        });
+        method.overloads.push(makeOverload(classitem));
         return false;
       } else {
         methodsByFullName[fullName] = classitem;

docs/yuidoc-p5-theme-src/scripts/tpl/class.html

@@ -6,7 +6,7 @@
 </div>
 <% } %>
 
-<% var fields = _.filter(things, function(item) { return item.itemtype === 'property' }); %>
+<% var fields = _.filter(things, function(item) { return item.itemtype === 'property' && item.access !== 'private' }); %>
 <% if (fields.length > 0) { %>
   <h4>Fields</h4>
   <p>
@@ -17,7 +17,7 @@ <h4>Fields</h4>
   </p>
 <% } %>
 
-<% var methods = _.filter(things, function(item) { return item.itemtype === 'method' }); %>
+<% var methods = _.filter(things, function(item) { return item.itemtype === 'method' && item.access !== 'private' }); %>
 <% if (methods.length > 0) { %>
   <h4>Methods</h4>
   <p>
@@ -29,4 +29,4 @@ <h4>Methods</h4>
     <% }); %>
     </table>
   </p>
-<% } %>
+<% } %>

docs/yuidoc-p5-theme-src/scripts/tpl/item.html

@@ -17,6 +17,10 @@ <h4>Description</h4>
 
   <span class='description-text'><%= item.description %></span>
 
+  <% if (item.extends) { %>
+    <p>Extends <a href="/reference/#/<%=item.extends%>" title="<%=item.extends%> reference"><%=item.extends%></a></p>
+  <% } %>
+
   <% if (item.module === 'p5.dom') { %>
     <p>This function requires you include the p5.dom library.  Add the following into the head of your index.html file:
       <pre><code class="language-javascript">&lt;script language="javascript" type="text/javascript" src="path/to/p5.dom.js"&gt;&lt;/script&gt;</code></pre>
@@ -135,12 +139,13 @@ <h4>Parameters</h4>
 </div>
 <% } %>
 
-<% if (item.return) { %>
+<% if (item.constructor || item.return) { %>
 <div>
-  <h4>Returns</h4>
-    <% if (item.return.type) { %>
+	<h4>Returns</h4>
+	  <% if (item.constructor) { %>
+      <p class='returns'><span class="param-type label label-info"><%=item.name%></span>: a new object</p>
+    <% } else if (item.return.type) { %>
       <p class='returns'><span class="param-type label label-info"><%=item.return.type%></span>: <%= item.return.description %></p>
     <% } %>
 </div>
-<% } %>
-
+<% } %>

docs/yuidoc-p5-theme-src/scripts/tpl/library.html

@@ -13,12 +13,12 @@ <h3><%= module.name %> library</h3>
   <% if (group.name !== module.name && group.name !== 'p5') { %>
     <a href="<%=group.hash%>" <% if (group.module !== module.name) { %>class="core"<% } %>><h4 class="group-name <% if (t == 0) { %> first<%}%>"><%=group.name%></h4></a>
   <% } %>
-  <% _.each(group.items, function(item) { %>
+  <% _.each(group.items.filter(function(item) {return item.access !== 'private'}), function(item) { %>
     <a href="<%=item.hash%>" <% if (item.module !== module.name) { %>class="core"<% } %>><%=item.name%><% if (item.itemtype === 'method') { %>()<%}%></a><br>
     <% t++; %>
   <% }); %>
   <% if (t >= Math.floor(totalItems/4)) { col++; t = 0; %>
     </div>
   <% } %>
 <% }); %>
-</div>
+</div>

docs/yuidoc-p5-theme-src/scripts/tpl/list.html

@@ -4,7 +4,7 @@ <h4 class="group-name" id="group-<%=group.name%>"><%=group.name%></h4>
   <% _.each(group.subgroups, function(subgroup, ind) { %>
     <dl>
     <% if (subgroup.name !== '0') { %>
-        <dt class="subgroup-<%=subgroup.name%>"><%=subgroup.name%></dt>
+        <dt class="subgroup-name subgroup-<%=subgroup.name%>"><%=subgroup.name%></dt>
     <% } %>
     <% _.each(subgroup.items, function(item) { %>
     <dd><a href="<%=item.hash%>" title="<%- striptags(item.description) %>"><%=item.name%><% if (item.itemtype === 'method') { %>()<%}%></a></dd>

docs/yuidoc-p5-theme-src/scripts/views/itemView.js

@@ -27,6 +27,7 @@ define([
       var isConstructor = cleanItem.is_constructor;
       var syntax = '';
       if (isConstructor) syntax += 'new ';
+      else if (cleanItem.static && cleanItem.class) syntax += cleanItem.class + '.';
       syntax += cleanItem.name;
 
       if (isMethod || isConstructor) {