yellow team mailing list archive
-
yellow team
-
Mailing list archive
-
Message #01330
[Merge] lp:~benji/juju-gui/doc-linter into lp:juju-gui
Benji York has proposed merging lp:~benji/juju-gui/doc-linter into lp:juju-gui.
Requested reviews:
Juju GUI Hackers (juju-gui)
For more details, see:
https://code.launchpad.net/~benji/juju-gui/doc-linter/+merge/131833
Add yuidoc linter.
https://codereview.appspot.com/6820047/
--
https://code.launchpad.net/~benji/juju-gui/doc-linter/+merge/131833
Your team Juju GUI Hackers is requested to review the proposed merge of lp:~benji/juju-gui/doc-linter into lp:juju-gui.
=== modified file 'Makefile'
--- Makefile 2012-10-29 09:01:09 +0000
+++ Makefile 2012-10-29 09:08:22 +0000
@@ -1,6 +1,12 @@
FILES=$(shell bzr ls -RV -k file | grep -v assets/ | grep -v app/templates.js | grep -v server.js)
-NODE_TARGETS=node_modules/chai node_modules/d3 node_modules/jshint \
- node_modules/yui node_modules/yuidoc
+# This list can be regenerated with this command (and then pasted in here):
+# find node_modules -maxdepth 1 -mindepth 1 -type d -printf 'node_modules/%f '
+NODE_TARGETS=node_modules/minimatch node_modules/cryptojs \
+ node_modules/yuidocjs node_modules/chai node_modules/less \
+ node_modules/.bin node_modules/node-markdown node_modules/rimraf \
+ node_modules/mocha node_modules/d3 node_modules/graceful-fs \
+ node_modules/should node_modules/jshint node_modules/expect.js \
+ node_modules/express node_modules/yui node_modules/yuidoc
TEMPLATE_TARGETS=$(shell bzr ls -k file app/templates)
DATE=$(shell date -u)
APPCACHE=app/assets/manifest.appcache
@@ -23,14 +29,16 @@
gjslint: virtualenv/bin/gjslint
@virtualenv/bin/gjslint --strict --nojsdoc --jslint_error=all \
- --custom_jsdoc_tags \
- property,default,since,method,module,submodule,namespace \
+ --custom_jsdoc_tags module,main,class,method,event,property,attribute,submodule,namespace,extends,config,constructor,static,final,readOnly,writeOnce,optional,required,param,return,for,type,private,protected,requires,default,uses,example,chainable,deprecated,since,async,beta,bubbles,extension,extensionfor,extension_for \
$(FILES)
jshint: node_modules/jshint
@node_modules/jshint/bin/hint $(FILES)
-lint: gjslint jshint
+yuidoc-lint: $(FILES)
+ @bin/lint-yuidoc
+
+lint: gjslint jshint yuidoc-lint
virtualenv/bin/gjslint virtualenv/bin/fixjsstyle:
@virtualenv virtualenv
=== modified file 'app/models/charm.js'
--- app/models/charm.js 2012-10-26 10:45:29 +0000
+++ app/models/charm.js 2012-10-29 09:08:22 +0000
@@ -164,8 +164,10 @@
is_subordinate: {writeOnce: true},
last_change: {
writeOnce: true,
+ /**
+ * Normalize created value from float to date object.
+ */
setter: function(val) {
- // Normalize created value from float to date object.
if (val && val.created) {
// Mutating in place should be fine since this should only
// come from loading over the wire.
@@ -184,6 +186,9 @@
requires: {writeOnce: true},
revision: {
writeOnce: true,
+ /**
+ * Parse the revision number out of a string.
+ */
setter: function(val) {
if (Y.Lang.isValue(val)) {
val = parseInt(val, 10);
@@ -194,6 +199,9 @@
scheme: {
value: 'cs',
writeOnce: true,
+ /**
+ * No matter what value is given, "cs" is the only allowed scheme.
+ */
setter: function(val) {
if (!Y.Lang.isValue(val)) {
val = 'cs';
=== modified file 'app/views/unit.js'
--- app/views/unit.js 2012-10-26 12:41:43 +0000
+++ app/views/unit.js 2012-10-29 09:08:22 +0000
@@ -27,7 +27,10 @@
template: Templates.unit,
/**
+ * Render the view.
+ *
* @method render
+ * @chainable
*/
render: function() {
var container = this.get('container');
=== added file 'bin/lint-yuidoc'
--- bin/lint-yuidoc 1970-01-01 00:00:00 +0000
+++ bin/lint-yuidoc 2012-10-29 09:08:22 +0000
@@ -0,0 +1,101 @@
+#!/usr/bin/env python
+
+import os
+import os.path
+import re
+import sys
+
+function_regex = re.compile('^ *([\w]+)\s*[:=]+ *function\s*\(')
+
+def find_functions(source):
+ for line_number, line in enumerate(source):
+ match = function_regex.match(line)
+ if match:
+ yield match.group(1), line_number
+
+
+def find_docs(function_name, line_number, boundry, source):
+ # Walk backwards from the function declaration to find some yuidoc. If we
+ # hit the previous function declaration ("boundry") before finding one,
+ # then there is none.
+ for current_line_number in range(line_number-1, boundry, -1):
+ source_line = source[current_line_number]
+ # If we enter or exit a block while scanning backwards without finding
+ # documentation, then there is none to be found.
+ if '{' in source_line or '}' in source_line:
+ return False
+ # If we find a documentation block, return its location.
+ if '/**' in source[current_line_number]:
+ return True
+ return False
+
+
+def check_file(file_name, undocumented):
+ # Every function.
+ functions = []
+ # Every function that has (unexpectedly) missing documentation.
+ missing_documentation = []
+ # Every function that has documentation but wasn't expected to.
+ falsely_undocumented = []
+ with open(file_name) as f:
+ source = f.readlines()
+ boundry = 0
+ for function_name, line_number in find_functions(source):
+ functions.append((file_name, function_name))
+ found_docs = find_docs(function_name, line_number, boundry, source)
+ boundry = line_number
+
+ # Report our findings.
+ code_location = '%s:%d "%s"' % (
+ file_name, line_number+1, function_name)
+ is_undocumented = (file_name, function_name) in undocumented
+ # If we found documentation for the function...
+ if found_docs:
+ # If it is listed as an undocumented function...
+ if is_undocumented:
+ #...report the incongruence.
+ falsely_undocumented.append(code_location)
+ # Otherwise if we found an undocumented funciton that is not
+ # supposed to be undocumented, report it.
+ elif not found_docs and not is_undocumented:
+ missing_documentation.append(code_location)
+
+ return functions, missing_documentation, falsely_undocumented
+
+
+def missing_undocumented(functions, undocumented):
+ missing = set(undocumented) - set(functions)
+ return ['%s "%s"' % x for x in missing]
+
+
+def main():
+ # Did we find any lint?
+ found_errors = False
+ # All of the functions found.
+ all_functions = []
+ for root, dirs, files in os.walk('app'):
+ with open('undocumented') as f:
+ undocumented = [tuple(line.split()) for line in f.readlines()]
+ for file_name in [os.path.join(root, name) for name in files]:
+ functions, missing_documentation, falsely_undocumented = (
+ check_file(file_name, undocumented))
+ all_functions.extend(functions)
+ for code_location in missing_documentation:
+ print code_location, 'missing yuidoc'
+ found_errors = True
+ for code_location in falsely_undocumented:
+ print code_location, 'erroneously listed as undocumented'
+ found_errors = True
+ # Ignore any asset directories.
+ dirs[:] = [dir for dir in dirs if dir != 'assets']
+
+ # Find functions that are listed as undocumented but don't actually exist.
+ for code_location in missing_undocumented(all_functions, undocumented):
+ print code_location, 'listed as undocumented but does not exist'
+ found_errors = True
+
+ return int(found_errors)
+
+
+if __name__ == '__main__':
+ sys.exit(main())
=== added file 'undocumented'
--- undocumented 1970-01-01 00:00:00 +0000
+++ undocumented 2012-10-29 09:08:22 +0000
@@ -0,0 +1,202 @@
+app/app.js callback
+app/app.js getModelURL
+app/models/charm.js compare
+app/models/charm.js failure
+app/models/charm.js initializer
+app/models/charm.js parse
+app/models/charm.js sync
+app/models/charm.js validator
+app/models/models.js add
+app/models/models.js comparator
+app/models/models.js get_informative_states_for_service
+app/models/models.js getModelById
+app/models/models.js getModelFromChange
+app/models/models.js getModelListByModelName
+app/models/models.js getNotificationsForModel
+app/models/models.js get_relations_for_service
+app/models/models.js get_units_for_service
+app/models/models.js has_relation_for_endpoint
+app/models/models.js initializer
+app/models/models.js on_delta
+app/models/models.js process_delta
+app/models/models.js removeOldest
+app/models/models.js reset
+app/models/models.js _setDefaultsAndCalculatedValues
+app/models/models.js setter
+app/models/models.js trim
+app/models/models.js update_service_unit_aggregates
+app/models/models.js valueFn
+app/store/charm.js find
+app/store/charm.js loadByPath
+app/store/charm.js _normalizeCharms
+app/store/charm.js setter
+app/store/charm.js success
+app/store/env.js add_relation
+app/store/env.js add_unit
+app/store/env.js connect
+app/store/env.js deploy
+app/store/env.js destroy_service
+app/store/env.js destructor
+app/store/env.js _dispatch_event
+app/store/env.js dispatch_result
+app/store/env.js _dispatch_rpc_result
+app/store/env.js expose
+app/store/env.js get_charm
+app/store/env.js get_endpoints
+app/store/env.js get_service
+app/store/env.js initializer
+app/store/env.js on_close
+app/store/env.js on_message
+app/store/env.js on_open
+app/store/env.js remove_relation
+app/store/env.js remove_units
+app/store/env.js resolved
+app/store/env.js _send_rpc
+app/store/env.js set_config
+app/store/env.js set_constraints
+app/store/env.js status
+app/store/env.js unexpose
+app/store/notifications.js evict
+app/store/notifications.js generate_notices
+app/store/notifications.js level
+app/store/notifications.js message
+app/store/notifications.js title
+app/views/charm.js _deployCallback
+app/views/charm.js initializer
+app/views/charm.js on_charm_data
+app/views/charm.js on_charm_deploy
+app/views/charm.js on_results_change
+app/views/charm.js on_search_change
+app/views/charm.js render
+app/views/charm-search.js deploy
+app/views/charm-search.js getInstance
+app/views/charm-search.js goBack
+app/views/charm-search.js hideDescription
+app/views/charm-search.js initializer
+app/views/charm-search.js killInstance
+app/views/charm-search.js mouseenter
+app/views/charm-search.js mouseleave
+app/views/charm-search.js _moveTooltip
+app/views/charm-search.js onCharmDeployClicked
+app/views/charm-search.js onFileChange
+app/views/charm-search.js onFileError
+app/views/charm-search.js onFileLoaded
+app/views/charm-search.js onFileRemove
+app/views/charm-search.js render
+app/views/charm-search.js setDefaultSeries
+app/views/charm-search.js setupOverlay
+app/views/charm-search.js showConfiguration
+app/views/charm-search.js showDescription
+app/views/charm-search.js showDetails
+app/views/charm-search.js _showErrors
+app/views/environment.js addRelation
+app/views/environment.js _addRelationCallback
+app/views/environment.js addRelationDrag
+app/views/environment.js addRelationDragEnd
+app/views/environment.js addRelationDragStart
+app/views/environment.js addRelationEnd
+app/views/environment.js addRelationStart
+app/views/environment.js ambiguousAddRelationCheck
+app/views/environment.js attachSceneEvents
+app/views/environment.js buildScene
+app/views/environment.js cancelRelationBuild
+app/views/environment.js click
+app/views/environment.js _destroyCallback
+app/views/environment.js destroyService
+app/views/environment.js destroyServiceConfirm
+app/views/environment.js detachSceneEvents
+app/views/environment.js drawRelation
+app/views/environment.js drawRelationGroup
+app/views/environment.js drawService
+app/views/environment.js fade
+app/views/environment.js _fire_zoom
+app/views/environment.js hide
+app/views/environment.js hideGraphListPicker
+app/views/environment.js initializer
+app/views/environment.js mouseenter
+app/views/environment.js mouseleave
+app/views/environment.js mouseout
+app/views/environment.js mouseover
+app/views/environment.js postRender
+app/views/environment.js processRelation
+app/views/environment.js processRelations
+app/views/environment.js relationClick
+app/views/environment.js removeRelation
+app/views/environment.js _removeRelationCallback
+app/views/environment.js removeRelationConfirm
+app/views/environment.js render
+app/views/environment.js renderSlider
+app/views/environment.js rescale
+app/views/environment.js serviceClick
+app/views/environment.js serviceDblClick
+app/views/environment.js serviceForBox
+app/views/environment.js setSizesFromViewport
+app/views/environment.js show
+app/views/environment.js showGraphListPicker
+app/views/environment.js show_service
+app/views/environment.js subordinateRelationsForService
+app/views/environment.js toggleControlPanel
+app/views/environment.js updateCanvas
+app/views/environment.js updateData
+app/views/environment.js updateServiceMenuLocation
+app/views/environment.js zoom_in
+app/views/environment.js zoom_out
+app/views/notifications.js close
+app/views/notifications.js getShowable
+app/views/notifications.js initializer
+app/views/notifications.js notificationSelect
+app/views/notifications.js notifyToggle
+app/views/notifications.js render
+app/views/notifications.js slowRender
+app/views/service.js _addUnitCallback
+app/views/service.js confirmDestroy
+app/views/service.js confirmRemoved
+app/views/service.js _destroyCallback
+app/views/service.js destroyService
+app/views/service.js doRemoveRelation
+app/views/service.js exposeService
+app/views/service.js _exposeServiceCallback
+app/views/service.js filterUnits
+app/views/service.js fitToWindow
+app/views/service.js getServiceTabs
+app/views/service.js initializer
+app/views/service.js modifyUnits
+app/views/service.js _modifyUnits
+app/views/service.js _removeRelationCallback
+app/views/service.js _removeUnitCallback
+app/views/service.js render
+app/views/service.js resetUnits
+app/views/service.js saveConfig
+app/views/service.js _setConfigCallback
+app/views/service.js _setConstraintsCallback
+app/views/service.js showErrors
+app/views/service.js unexposeService
+app/views/service.js _unexposeServiceCallback
+app/views/service.js updateConstraints
+app/views/unit.js confirmRemoved
+app/views/unit.js confirmResolved
+app/views/unit.js confirmResolvedRelation
+app/views/unit.js doRemoveUnit
+app/views/unit.js doResolvedRelation
+app/views/unit.js doResolvedUnit
+app/views/unit.js initializer
+app/views/unit.js _removeUnitCallback
+app/views/unit.js _resolvedRelationCallback
+app/views/unit.js _resolvedUnitCallback
+app/views/unit.js retry
+app/views/unit.js retryRelation
+app/views/utils.js action
+app/views/utils.js addSVGClass
+app/views/utils.js bindModelView
+app/views/utils.js console
+app/views/utils.js get
+app/views/utils.js hasSVGClass
+app/views/utils.js humanizeNumber
+app/views/utils.js native
+app/views/utils.js noop
+app/views/utils.js removeSVGClass
+app/views/utils.js renderable_charm
+app/views/utils.js scale
+app/views/utils.js set
+app/views/utils.js toggleSVGClass
+app/views/utils.js translate
Follow ups
