diff --git a/doc/integration.texi b/doc/integration.texi index c5425f3..61690f8 100644 --- a/doc/integration.texi +++ b/doc/integration.texi @@ -17,209 +17,10 @@ downloading pre-built packages. Depending on what you are doing, you may not have to build ease.js at all. @menu -* Source Tree:: Describes the project source tree * Building:: How to build ease.js * Including:: Including ease.js in your own project @end menu -@node Source Tree -@section Source Tree -Before building, you need to get a hold of the source tree. Either download an -archive (tarball, zip, etc), or clone the Git repository. We will do the latter. -Feel free to clone from your favorite source. - -@example - # to clone from GitHub (do one or the other, not both) - $ git clone git://github.com/mikegerwitz/easejs - - # to clone from Gitorious (do one or the other, not both) - $ git clone git://gitorious.org/easejs/easejs.git -@end example - -The repository will be cloned into the @file{./easejs} directory. Let's take a -look around. - -@example - $ cd easejs - $ ls -d */ - doc/ lib/ test/ tools/ -@end example - -The project contains four main directories in addition to the root directory: - -@table @file -@item ./ -The root directory contains basic project files, such as @file{README}, -@file{Makefile} and @file{index.js}. - -@item doc/ -Contains documentation source files (you are currently reading part of it - the -manual). - -@item lib/ -Contains the actual source code for the various modules. - -@item test/ -Contains unit tests. - -@item tools/ -Various tools used during build process. -@end table - -Let's take a look at each directory in more detail. - -@menu -* Root Directory:: Contains basic project files -* Doc Directory:: Contains source documentation files (manual) -* Lib Directory:: Contains project source files (modules) -* Test Directory:: Contains unit tests -* Tools Directory:: Contains build tools -@end menu - -@node Root Directory -@subsection Root Directory -The root directory contains basic project files for common operations. - -@table @file -@item index.js -This file is loaded automatically when @samp{require( 'easejs' )} is used. - -@item LICENSE -Contains the project license. - -@item Makefile -Invoked by the @command{make} command. Used for building ease.js. - -@item package.json -Used by @command{npm}, a package manager for Node.js, to automate installation. - -@item README.md -Serves as a quick reference for the project, in markdown@footnote{See -@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen -because it is displayed nicely on GitHub. - -@item TODO -Incomplete tasks. Future direction of the project. If you're looking to help -out, take a look at this file to see what needs to be done. -@end table - -These files will be discussed in further detail when they are actually used. - - -@node Doc Directory -@subsection Doc Directory -The @file{doc/} directory contains the source files for the manual. The source -files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.} -format. Instructions for compiling the documentation are included later in this -chapter. - -API documentation is @emph{not} included in this directory. It is generated from -the source code. - - -@node Lib Directory -@subsection Lib Directory -The @file{lib/} directory contains the source code for the project. Each source -file represents a single CommonJS module and is written in JavaScript. - -@table @file -@item class.js -The main Class module. This contains all the functionality necessary to declare -and extend classes, implement interfaces, etc. This is the bulk of ease.js. - -@item interface.js -Allows declaration and extension of Interfaces. - -@item member_builder.js -Responsible for building class members. - -@item propobj.js -Builds the internal property instance object that is passed around to methods of -specific class instances. This is the magic behind visibility support, and -therefore encapsulation. - -@item prop_parser.js -Parses property strings. Note that the name refers to JavaScript properties, -which are any members of an object. Therefore, this module works on all members. - -@item util.js -General utility functions for property parsing, object cloning, browser -fallbacks, etc. -@end table - -Unless you are developing for ease.js, you needn't concern yourself with these -files. @file{index.js}, in the root directory, contains mappings to these files -where necessary, exposing the useful portions of the API for general use. You -can use ease.js without even recognizing that the @file{lib/} directory even -exists. - - -@node Test Directory -@subsection Test Directory -The @file{test/} directory contains all the unit tests for the project. ease.js -follows a test-driven development model. Every single aspect of the framework is -tested to ensure that features work as intended both server-side and across all -supported web browsers. The tests also ensure that bugs are not introduced for -anything that has been covered. This should also give outside developers -confidence. If a developer makes a modification to ease.js and does not cause -any failing tests, it's likely that their change didn't have negative -consequences on the integrity of the framework. - -All tests are prefixed with @samp{test-}, followed by the name of the module, -followed optionally by the specific part of the module that is being tested. The -tests are written in JavaScript and use Node.js's @file{assert} module. They may -be run individually or at once during the build process. - -Tests are discussed later on in this chapter. - - -@node Tools Directory -@subsection Tools Directory -The @file{tools/} directory contains scripts and data necessary for the build -process. The tools are shell scripts that may be run independently of the build -process if you find them to be useful. The remaining files are data to accompany -those tools. - -@table @file -@item combine -Concatenates all the modules and wraps them for client-side deployment. If -requested, the tests are also wrapped and concatenated so that they may be run -in the web browser. The contents are stripped of trailing commas using the -@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can -use whatever process he/she wishes to do so. In the future, minification will be -part of the build script. - -@item rmtrail -Removes trailing commas from object and array definitions. Reads from standard -in. @emph{This script is not intelligent.} It was designed to work with ease.js. -It does not, for example, check to ensure that it is not removing commas from -within strings. This would not be a difficult addition, but is currently -unnecessary. Use caution when using this tool outside of ease.js. - -@item browser-test.html -Skeleton page to be used after the build process. Runs ease.js unit tests in the -web browser and reports any failures. This is very important to ensure that -ease.js operates consistently between all supported browsers. The tests that are -run are the same exact tests that are run server-side. - -@item combine-test.tpl -Contains a client-side implementation of any modules required for testing. This -file contains mainly assertions. It is included by the @command{combine} script -when tests are requested. - -@item combine.tpl -Contains the basic functionality required to get CommonJS modules working -client-side. This is a very basic implementation, only doing what is necessary -for ease.js to work properly. It is not meant to be a solution for all of your -client-side CommonJS problems. -@end table - -While the tools may be useful outside of ease.js in some regard, please note -that they have been tailored especially for ease.js. They do not contain -unnecessary features that ease.js does not need to make use of. Therefore, you -may need to adapt them to your own project and individual needs should you -decide to use them in your own projects. - @node Building @section Building diff --git a/doc/manual.texi b/doc/manual.texi index f4db124..42e6ff7 100644 --- a/doc/manual.texi +++ b/doc/manual.texi @@ -44,11 +44,13 @@ This manual is for ease.js, version 0.1.0-pre. @menu * About:: About the project * Integration:: How to integrate ease.js into your project +* Source Tree:: Overview of source tree * License:: Document License @end menu @include ./about.texi @include ./integration.texi +@include ./source-tree.texi @include ./license.texi @bye diff --git a/doc/source-tree.texi b/doc/source-tree.texi new file mode 100644 index 0000000..7f03086 --- /dev/null +++ b/doc/source-tree.texi @@ -0,0 +1,208 @@ +@c This document is part of the ease.js manual +@c Copyright (c) 2011 Mike Gerwitz +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover +@c Texts. A copy of the license is included in the section entitled ``GNU +@c Free Documentation License''. + +@node Source Tree +@appendix Source Tree +Before building, you need to get a hold of the source tree. Either download an +archive (tarball, zip, etc), or clone the Git repository. We will do the latter. +Feel free to clone from your favorite source. + +@example + # to clone from GitHub (do one or the other, not both) + $ git clone git://github.com/mikegerwitz/easejs + + # to clone from Gitorious (do one or the other, not both) + $ git clone git://gitorious.org/easejs/easejs.git +@end example + +The repository will be cloned into the @file{./easejs} directory. Let's take a +look around. + +@example + $ cd easejs + $ ls -d */ + doc/ lib/ test/ tools/ +@end example + +The project contains four main directories in addition to the root directory: + +@table @file +@item ./ +The root directory contains basic project files, such as @file{README}, +@file{Makefile} and @file{index.js}. + +@item doc/ +Contains documentation source files (you are currently reading part of it - the +manual). + +@item lib/ +Contains the actual source code for the various modules. + +@item test/ +Contains unit tests. + +@item tools/ +Various tools used during build process. +@end table + +Let's take a look at each directory in more detail. + +@menu +* Root Directory:: Contains basic project files +* Doc Directory:: Contains source documentation files (manual) +* Lib Directory:: Contains project source files (modules) +* Test Directory:: Contains unit tests +* Tools Directory:: Contains build tools +@end menu + +@node Root Directory +@section Root Directory +The root directory contains basic project files for common operations. + +@table @file +@item index.js +This file is loaded automatically when @samp{require( 'easejs' )} is used. + +@item LICENSE +Contains the project license. + +@item Makefile +Invoked by the @command{make} command. Used for building ease.js. + +@item package.json +Used by @command{npm}, a package manager for Node.js, to automate installation. + +@item README.md +Serves as a quick reference for the project, in markdown@footnote{See +@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen +because it is displayed nicely on GitHub. + +@item TODO +Incomplete tasks. Future direction of the project. If you're looking to help +out, take a look at this file to see what needs to be done. +@end table + +These files will be discussed in further detail when they are actually used. + + +@node Doc Directory +@section Doc Directory +The @file{doc/} directory contains the source files for the manual. The source +files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.} +format. Instructions for compiling the documentation are included later in this +chapter. + +API documentation is @emph{not} included in this directory. It is generated from +the source code. + + +@node Lib Directory +@section Lib Directory +The @file{lib/} directory contains the source code for the project. Each source +file represents a single CommonJS module and is written in JavaScript. + +@table @file +@item class.js +The main Class module. This contains all the functionality necessary to declare +and extend classes, implement interfaces, etc. This is the bulk of ease.js. + +@item interface.js +Allows declaration and extension of Interfaces. + +@item member_builder.js +Responsible for building class members. + +@item propobj.js +Builds the internal property instance object that is passed around to methods of +specific class instances. This is the magic behind visibility support, and +therefore encapsulation. + +@item prop_parser.js +Parses property strings. Note that the name refers to JavaScript properties, +which are any members of an object. Therefore, this module works on all members. + +@item util.js +General utility functions for property parsing, object cloning, browser +fallbacks, etc. +@end table + +Unless you are developing for ease.js, you needn't concern yourself with these +files. @file{index.js}, in the root directory, contains mappings to these files +where necessary, exposing the useful portions of the API for general use. You +can use ease.js without even recognizing that the @file{lib/} directory even +exists. + + +@node Test Directory +@section Test Directory +The @file{test/} directory contains all the unit tests for the project. ease.js +follows a test-driven development model. Every single aspect of the framework is +tested to ensure that features work as intended both server-side and across all +supported web browsers. The tests also ensure that bugs are not introduced for +anything that has been covered. This should also give outside developers +confidence. If a developer makes a modification to ease.js and does not cause +any failing tests, it's likely that their change didn't have negative +consequences on the integrity of the framework. + +All tests are prefixed with @samp{test-}, followed by the name of the module, +followed optionally by the specific part of the module that is being tested. The +tests are written in JavaScript and use Node.js's @file{assert} module. They may +be run individually or at once during the build process. + +Tests are discussed later on in this chapter. + + +@node Tools Directory +@section Tools Directory +The @file{tools/} directory contains scripts and data necessary for the build +process. The tools are shell scripts that may be run independently of the build +process if you find them to be useful. The remaining files are data to accompany +those tools. + +@table @file +@item combine +Concatenates all the modules and wraps them for client-side deployment. If +requested, the tests are also wrapped and concatenated so that they may be run +in the web browser. The contents are stripped of trailing commas using the +@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can +use whatever process he/she wishes to do so. In the future, minification will be +part of the build script. + +@item rmtrail +Removes trailing commas from object and array definitions. Reads from standard +in. @emph{This script is not intelligent.} It was designed to work with ease.js. +It does not, for example, check to ensure that it is not removing commas from +within strings. This would not be a difficult addition, but is currently +unnecessary. Use caution when using this tool outside of ease.js. + +@item browser-test.html +Skeleton page to be used after the build process. Runs ease.js unit tests in the +web browser and reports any failures. This is very important to ensure that +ease.js operates consistently between all supported browsers. The tests that are +run are the same exact tests that are run server-side. + +@item combine-test.tpl +Contains a client-side implementation of any modules required for testing. This +file contains mainly assertions. It is included by the @command{combine} script +when tests are requested. + +@item combine.tpl +Contains the basic functionality required to get CommonJS modules working +client-side. This is a very basic implementation, only doing what is necessary +for ease.js to work properly. It is not meant to be a solution for all of your +client-side CommonJS problems. +@end table + +While the tools may be useful outside of ease.js in some regard, please note +that they have been tailored especially for ease.js. They do not contain +unnecessary features that ease.js does not need to make use of. Therefore, you +may need to adapt them to your own project and individual needs should you +decide to use them in your own projects. + +