Permalink
Browse files

Documentation changes, also splitting up files.

  • Loading branch information...
1 parent dc6f2f3 commit 1947a5f442d7325810dc02c364f0c58415ef09dc @davebalmer committed Jun 8, 2010
View
22 ABOUT
@@ -4,34 +4,33 @@ About
=====
jo is a lightweight JavaScript framework designed for HTML5 apps.
-Small enough for mobile devices yet powerful enough for desktop applications.
jo does
--------
- Embrace JavaScript's object model and loosely typed nature
- Leverage CSS3 to handle as much of the pretty presentation and animation as possible
- Provide a consistent and modular event model between objects
-- Reduce levels of pseudo-namespacing to improve performance
- Wrap DOM and device-specific events into a cohesive gesture system
- Insulate developers from different persistent storage solutions
- Play nicely with other libraries like PhoneGap
jo doesn't
-----------
+- Use a lot of resources
- Depend on other frameworks
+- Have a lot of browser dependent code
+- Require detailed knowledge of the DOM
- Force you to deeper into its framework than you want to go
-- Take up a ton of memory or hard drive space
-- Eat a bunch of your CPU cycles
- Use `$` and other arcane looking symbols in place of proper identifiers
Author
------
Dave Balmer:
-[homepage](http://davebalmer.wordpress.com),
-[twitter @balmer](http://twitter.com/balmer),
+[davebalmer.wordpress.com](http://davebalmer.wordpress.com),
+[follow @balmer on Twitter](http://twitter.com/balmer),
or email [dbalmerjr@gmail.com](mailto:dbalmerjr@gmail.com)
@@ -40,9 +39,8 @@ Philosophy
If you want to jam an existing web page into an application framework, jo probably isn't
for you. jo is designed to create applications. While it will play nicely with a mixture
-of new and old web development techniques, its aim is to serve as a cross-platform
-framework. jo treats WebKit and HTML5 as a development stack, and does not require a deep
-knowledge of DOM manipulation.
+of new and old web development techniques, it uses HTML5 as a development stack and does
+not require direct DOM manipulation.
Application Stack
-----------------
@@ -59,9 +57,9 @@ Documentation
All documentation for the framework is based on
[Markdown](http://daringfireball.net/projects/markdown/syntax)
-and provides a simple, natural and flexible way to document
-the code.
+and provides a simple, natural and flexible way to document the code. This simple set
+of `perl` scripts has become its own tool called joDoc.
-This simple set of `perl` scripts has become its own tool called joDoc.
+> Currently joDoc is included with jo, but in the future it will have its own codebase.
- - -
View
1 README
@@ -23,7 +23,6 @@ you want the whole enchilada.
If you're not up for building the library yourself, there's nothing wrong with
downloading the latest stable release, all built and ready to plug in from:
-
[joApp.com](http://joapp.com)
View
@@ -1,6 +1,10 @@
docs: *.mdown
# docker `find ../js -name *.js` > tmp.md
- ../jodoc/docker ../js/*.js > ./tmp.md
+ ../jodoc/docker ../js/core/*.js > ./tmp.md
+ echo "\n- - -\n" >> ./tmp.md
+ ../jodoc/docker ../js/ui/*.js >> ./tmp.md
+ echo "\n- - -\n" >> ./tmp.md
+ ../jodoc/docker ../js/data/*.js >> ./tmp.md
cat ../ABOUT ../README ../LICENSE `find .. -name "*.mdown"` ./tmp.md | markdown | ../jodoc/autolink > html/raw.html
../jodoc/htmlhead ./html/raw.html > ./html/index.html
rm tmp.md
View
@@ -6,7 +6,7 @@ coding patterns: singleton, base class, subclass, and module. All of these
are found in modern JavaScript implementations. A good reference to have
while developing your app is
[JavaScript: The Good Parts](http://javascript.crockford.com/)
-by Douglas Crockford.
+by Douglas Crockford (O'Reilly Press)
Singleton
---------
@@ -41,16 +41,20 @@ A base class looks something like:
};
MyClass.prototype = {
mymethod: function() {
- // some custom method
+ // some method
+ },
+
+ myothermethod: function() {
+ // another method
}
};
Subclass
--------
-JavaScript doesn't have classes and subclasses. But it does know how to make
-copies of an object, and keeps track of "inheritance" through its prototype
-chain. A subclass in jo looks something like this:
+Strictly speaking, JavaScript doesn't have classes and subclasses. But it does
+know how to make copies of an object, and keeps track of "inheritance" through
+its prototype chain. A subclass in jo looks something like this:
MySubclass = function(x, y) {
//constructor
@@ -65,17 +69,18 @@ chain. A subclass in jo looks something like this:
}
});
-A couple things to note. We've augmented the Function object in JavaScript to
-have an `extend()` method. This is really just some syntactic sugar that makes it
-easier to extend an object, giving us a pseudo-subclass which has syntax that's
-not too hard to digest. The advantage here is we're using JavaScript's natural
-object model behind the scenes. We're not creating any extra fluff, just automating
-the process somewhat.
+A couple things to note. jo augments the Function object in JavaScript to
+have an `extend()` method. This is just some syntactic sugar which makes it
+easier to extend an object, giving us a pseudo-subclass with syntax that's
+not too awkward. The advantage here is we're using JavaScript's natural
+object model behind the scenes. We're not creating any extra fluff, just
+automating the process somewhat.
Note that objects created using prototypal inheritance also get the benefit of
-using JavaScript's built-in `instanceof` operator, and that tests work up
+using JavaScript's built-in `instanceof` operator which works up the
prototype chain. For example:
+ // given this new subclass
var someobject = new MySubclass(1, 2);
// both of these tests are "true"
@@ -84,7 +89,7 @@ prototype chain. For example:
You may also notice a "call to super" comment in our `MySubclass` constructor.
This is a convenient coding pattern which makes it easier to create subclasses,
-and methods which augment the superclass' functionality. Like this:
+with methods that augment the superclass' functionality. Like this:
MySubclass.extend(MyClass, {
mynewmethod: function() {
@@ -94,13 +99,11 @@ and methods which augment the superclass' functionality. Like this:
mymethod: function() {
this.x += 5;
- // call super's mymethod with this object's context
- MyClass.mymethod.apply(this, arguments);
+ // call super's mymethod() with this object's context
+ MyClass.prototype.mymethod.apply(this, arguments);
}
});
-It may look slightly evil at first, but after a few uses this approach (using
-the `call` or `apply` methods built into `Function`) gives us a powerful way
-to get more of the benefits of subclassing you'd find in languages with
-classical inheritance but without having to step outside of JavaScript's
-natural object model.
+It may look slightly odd at first, but this approach gives us more of the
+benefits of subclassing you'd find in other languages without having to step
+outside of JavaScript's natural object model.
@@ -1,12 +1,13 @@
Observer Pattern
================
-jo uses a variant on this OOP pattern quite extensively for asynchronous notifications
-between objects. When you think about JavaScript, most of the interesting things that
+jo uses a variant on this OOP pattern quite extensively for notifications
+between objects.
+
+When you think about JavaScript, most of the interesting things that
happen are asynchronous: XHR calls, loading scripts, accessing at database, making
device-specific system calls; even user interactions are all asynchronous in nature.
Instead of trying to hide from this often complex-looking stuff, jo embraces it and
provides a scheme to wrap all these different use cases in a consistent interface
using joSubject.
-
View
@@ -3,7 +3,7 @@ PhoneGap
This excellent, lightweight mobile application library by [Nitobi](http://phonegap.com)
neutralizes device differences and provides a stable webkit application shell. jo is
-designed to use PhoneGap out of the box, and it's highly recommended.
+designed to work with PhoneGap out of the box, and it's highly recommended.
LawnChair
=========
View
@@ -10,11 +10,10 @@ stylesheet that most closely matches your application (or device native controls
HTML Tags
=========
-One other trick it exploits is the fact that modern browser engines treat unknown
+One feature jo exploits is the fact that modern browser engines treat unknown
tags as -- _tags_. So instead of mucking up your application's DOM and CSS space with
-a horde of `div` tags with different CSS classes, it's using namespaced tags which
-are outside of your document's CSS tag spacing (except body, everything inherits
-from that).
+a horde of `div` tags with different CSS classes, it uses namespaced tags which
+are outside of your document's typical CSS name space (except `body`).
Special Tag Examples
--------------------
@@ -29,10 +28,3 @@ Special Tag Examples
One side benefit of this is that it is possible to load styled HTML content from
another source and not have that content's CSS corrupt your application's user
interface.
-
-> _Note:_ this has only been tested with WebKit and Gecko engines. This might fail
-> spectacularly on less capable engines, but it's likely that those crude devices
-> would need some special love in the way of a special library build of the code
-> in any case.
-
-
View
@@ -18,7 +18,7 @@ print <<ENDDOC
<meta name="format-detection" content="false">
</head>
<body>
-<cite>Jo<cite>JavaScript Application Framework for HTML5</cite></cite>
+<cite>Jo<cite>JavaScript App Framework</cite></cite>
$file
View
@@ -1,13 +1,8 @@
joDoc
=====
-joDoc is a markup-based code documentation scheme for JavaScript. It was created out of
-frustration working with various documentation systems currently available.
-
-JavaScript is an extremely expressive language which is often difficult to describe in
-terms of meta data and fields. Often, important information that needs to be documented
-just doesn't fit into a neat, tidy spot.
-
+joDoc is a plain text code documentation scheme for JavaScript. It was created out of
+frustration felt working with various documentation systems available.
Source code formatting
----------------------
@@ -52,26 +47,29 @@ Can't get much more flexible than that.
Comparison
----------
+JavaScript is an extremely expressive language which is often difficult to describe in
+terms of meta data and fields. Often, important information that needs to be documented
+just doesn't fit into a neat, tidy spot.
+
### jsdoc
-jsdoc in its various incarnations and some of its spawn like yuidoc take that approach
-that "what was good for Java is fine for JavaScript". All these flavors are based on
-javadoc formatting, and have been in use for some years.
+jsdoc in its various incarnations and some of its spawn like yuidoc take the approach
+that "what is good for Java is good for JavaScript". All these flavors are based on
+javadoc formatting, and have been in use for some time.
Aside from the regimented markup being a bit odd to read (admit it, even Java developers
don't _love_ it), it suffers from an inflexibility with regard to all the coding
-patterns available with JavaScript. Basically, it fails due to the same reason that all
-the JavaScript OOP libraries which attempt to make a classical OOP model (i.e. Java)
-abstraction on top of JavaScript's natural way of doing things. These solutions, while
-influential in the idea that _some_ form consistent coding approach could help us make
-better code, have been left behind as unnecessary.
+patterns available with JavaScript. Basically, it fails due for the same reason that all
+JavaScript libraries which attempt to subvert JavaScript's natural object model fail.
+These solutions, while influential in the idea that _some_ form consistent coding
+approach could help us make better code, are not in the spirit of embracing JavaScript.
-Why then do so many developers continue to use a documentation tool which was born of the
-same well-meaning yet mismatched logic?
+Why then do so many developers continue to use a _documentation_ tool which was born
+of the same well-meaning yet misguided logic of "let's pretend JavaScript is Java"?
-###Natural Docs
+### Natural Docs
-Excellent effort, but complex to setup and also tries to make a regimented system for
+Excellent effort, but complex to set up and also tries to make a regimented system for
documenting source code. It is extendable, but again, we have a documentation solution
which is trying to force JavaScript into a more limited set of features.
@@ -120,10 +118,10 @@ For those who want more insight into how the documentation is created:
This produces a bundle of files which can be used a couple of ways:
-1. a loose set of files which is used by the joDoc application (written
+1. A loose set of files which is used by the joDoc application (written
using the jo library, of course)
-2. an alternative "single page" view of all the documentation (which some
+2. An alternative "single page" view of all the documentation (which some
people really like)
3. Your own collection of files with some other organization means (which
View
@@ -6,7 +6,6 @@ CORE = log.js \
yield.js \
chain.js \
clipboard.js \
- local.js \
all:
cat $(CORE) >> ../jo.js
View
@@ -2,10 +2,11 @@
joChain
========
- Class which strings asyncronous calls together. In serious need
- of rework; doesn't meet original goal of serializing these calls.
- This class might become deprecated.
+ Class which strings asyncronous calls together.
+ > In serious need of rework; doesn't meet original goal of sequencing
+ > these calls. This class might also become deprecated.
+
Methods
-------
View
@@ -27,11 +27,6 @@
supports selections, `cut()` will automatically remove the selection after
copying its contents. Otherwise, `cut()` will work the same as `copy()`.
- Requires
- --------
-
- - jsPreference
-
*/
joClipboard = {
data: "",
View
@@ -2,13 +2,23 @@
joEvent
========
- Singleton with event model utility medthods.
+ Singleton with DOM event model utility methods. Ideally, application-level
+ code shouldn't have to use this, but library code does.
Methods
-------
- `on(HTMLElement, event, Function, context, data)`
+
+ Set a DOM event listener for an HTMLElement which calls a given Function
+ with an optional context for `this` and optional static data.
+
- `stop(event)`
+
+ Prevent default and stop event propogation.
+
- `getTarget(event)`
+
+ Returns the HTMLElement which a DOM event relates to.
*/
View
@@ -1,19 +1,4 @@
-/**
- joLocal
- =======
-
- Localized string lookup function.
-
- > This feature is still under review and development, so proceed with caution.
-
- Use
- -----
-
- var label = joLocal("name");
-
-
- Setting the Language
- --------------------
-
- See the jo global for more on how to do this.
+/*
+ not used at this time
*/
+
View
@@ -18,10 +18,6 @@
produce a string version of each argument (where appropriate; browser debuggers tend to
display objects nicely) in the same console line. Simple, effective, easy to use.
- > Note that even for browser development, this is preferable to blindly using
- > `console.log()`, because you're going to get silent errors on FireFox if the user
- > isn't running FireBug, for example.
-
*/
joLog = function() {
Oops, something went wrong.

0 comments on commit 1947a5f

Please sign in to comment.