Additional comments for the function header
Brett Zamir
I see on https://github.com/kvz/phpjs/wiki/DeveloperGuidelines that
there is already a helpful section explaining the header comments.
I wanted to add the following to the wiki, but wanted to get your
approval (or suggestions) before moving forward.
These additional properties are meant to give more structured
information about our functions, and their level of development. I don't
expect doing a thorough review, though I am considering doing this for
array functions since I'm revisiting the functions for the sake of
PHPJS_Array.
How do these sound?
(We could make clear in the Developer Guidelines that the goldstar
comments should only be added in consultation with the whole team or
core contributors.)
// * goldstar: Attribute=value (mostly all boolean) pairs to
indicate compliance on these dimensions:
1) strict (boolean) - works with strict mode; this
information could be parsed for use within our namespaced version, but
since we use "this" in the non-namespaced version to refer to the global
(window) object when invoking our dependency functions, we often cannot
use strict mode in such cases)
2) Unicode (boolean) - supports (or is orthogonal
to) non-BMP characters
3) constants (boolean) - supports (or is
orthogonal to) PHP constants, whether expressed as numbers, strings, or
arrays of strings
4) exceptions (boolean) - support PHP style
errors, warnings, and notices
5) ini (boolean|Array) - supports (or is
orthogonal to) PHP INI settings; true for complete support where
possible, false if not complete, and where support is dependent on the
environment, an array of strings referring to the supported environments
(e.g,. if some settings only work in CommonJS server-side JavaScript, it
would be ini=['CommonJS'])
6) complete (boolean|Array) - True if support
fully covers the functionality of the PHP API. If support is partial,
including all 1) arguments, 2) return value types (or our standard
equivalents), 3) global setters (if the function sets globals in PHP,
make sure we give our own configuration option to let it work either as
a true global on the window object or as a property directly on the
namespace object).
7) modular (boolean) - True if architected to use
1) /* BEGIN REDUNDANT */ and /* END REDUNDANT */ to mark blocks of code
which could be safely moved to the constructor (in the namespaced
version), e.g., code which checks if the this.php_js.ini global is
built, and if not, adds it. 2) /* BEGIN STATIC */and /* END STATIC */ to
mark blocks of static code (such as private utility functions) which
could be safely moved to the top of the anonymous namespace in which the
PHP_JS "class" is built. These blocks should be identical (in name and
behavior) when placed in different functions, so they can be safely removed.
8) documented (Array) - A subjective decision
about whether the code is adequately documented in terms of adequate
(and clear) 'notes', 'examples', 'internal-comments', 'jsdoc'
9) brevity (boolean) - Whether the function is as
brief as is reasonable (before whitespace-packing)
10) performance (boolean) - Whether the function
has been optimized for optimal performance
12) extras (boolean) - Whether it non-obtrusively
supports extra php.js features like RegExp or Date objects as arguments
or php.js-specific INI settings. Not required for a complete "gold star"
rating.
13) experimental (boolean) Whether it requires an
experimental implementation such as a callback as an always-final
asynchronous argument, etc.
// * environment (Array): e.g., core, browser, CommonJS, Gecko,
Node; multiple values can be specified; "core" should be used if all
functionality will work regardless of environment (though see the
"version" attribute); "browser" should be specified if a browser
environment is required (e.g., use of the DOM, though jsDOM might help
avoid that condition for server-side JavaScript). "CommonJS" should be
indicated if it will work across server-side implementations; if a
particular module and version is entailed, this could be separated by a
colon, like "CommonJS:Modules:1.1.1:sockets".
// * version (string): This attribute should usually not be
necessary as we attempt to work with all versions of ECMAScript
available in browsers in use today; however, should a function only be
implementable with a specific version, we can indicate that here)
Note that I mentioned "jsdoc" above. I wanted to revisit that because I
really think having such JSDoc syntax will, besides allowing IDEs to
take advantage of the info, allow us to better document the allowable
values we've anticipated for arguments and return values.
Take care,
Brett