update docs

dapphub · Mar 1, 2016 · 2637f9f · 2637f9f
1 parent 0b7731c
commit 2637f9f
Show file tree

Hide file tree

Showing 6 changed files with 34 additions and 28 deletions.
diff --git a/doc/definitions.md b/doc/definitions.md
@@ -1,5 +1,7 @@
 ## Definitions
 
+Last updated 0.2.0
+
 #### basics
 
 The term "contract" introduces ambiguity. We use the familiar terms "class" and "object" instead.

diff --git a/doc/deployscript.md b/doc/deployscript.md
@@ -1,11 +1,11 @@
-Dapples script language is a domain specific language(DSL) which allows to write
-arbitrary scripts to automatically set up contract systems on a specified chain.
+Dapple understands a simple domain specific language which allows you to write
+scripts to automatically set up contract systems on a specified chain.
 This includes deploying and calling contracts, logging values, persistently
 saving values, importing values from the current environment and dependant packages.
 
 ## How to
-A script is usually written to the root package directory and can have
-an arbitrary name. It can be called with `dapple run <script> [--force] [--no-simulation] [options]`
+A script is usually written either to the package root or a `scripts` directory.
+It can be called with `dapple run <script> [--force] [--no-simulation] [options]`
 
 If only a specific expression needs to be executed it can be called without a 
 script with `dapple step <string> [options]`.

diff --git a/doc/install_publish.md b/doc/install_publish.md
@@ -1,21 +1,23 @@
 ## Install and Publish
 
+Note: DapphubDB address not finalized, use caution until this notice is removed.
+
 ### DapphubDb
 
-Dapple is capable of interacting (installing and publishing packages) with an
-on chain package registry. Ipfs is used as a storage and data transfear layer.
+Dapple is capable of interacting with an on-chain package registry for installing
+and publishing packages. IPFS is used as a storage and data transfer layer.
 A dapple package is content addressed by an ipfs hash. The hash is stored along
-with the package name and version on the ethereum chain.
-In order for this to work the user must have a working chain and ipfs connection
+with the package name and semantic version on the ethereum chain.
+In order for this to work the user must have a working Ethereum and IPFS connection
 specified in his `~/.dapplerc`.
 
 #### installing
 
-The commandline command to isntall a package from the registry is:
+The command to install a package from the registry is:
 
 `dapple install [--save] [options] [<package> <url-or-version>]`
 
-E.g. `dapple install dappsys 1.0.0 --save -e morden`
+E.g. `dapple install dappsys 0.1.0 --save`
 
 This will install dappsys package at version 1.0.0 from the registry which is
 deployed to morden chain and save this dependecy to the local dappfile, which
@@ -27,15 +29,17 @@ can be installed with `dapple install`:
 ```
 [...]
 dependencies:
-  dappsys: 1.0.0
+  dappsys: 0.1.0
 ```
 
 #### publishing
 
-To prevent poluting the global namespace, publishing is currently restricted
-to the internal dapple developers. This is ensured by the authentication system
-provided by dappsys framework. After a initial test phase a publish use will
-be introduced to the public.
+To prevent pollution of the global namespace, publishing is currently restricted
+to a few trusted dapple developers who curate the registry.
+This is ensured by the authentication system provided by [dappsys](https://github.com/nexusdev/dappsys) framework.
+The intent is to enable open publication as soon as some kind of arbitration or at least
+initial distribution scheme is invented. It is possible to update the system in-place,
+and there will be no need to redeploy the data store contract which dapple reads from.
 
 The command `dapple publish [options]` will build the current package based on
 the specifications given in the local dappfile and publish it to the registry

diff --git a/doc/test.md b/doc/test.md
@@ -1,4 +1,4 @@
-Dapple provides a VM test harness so you can write your tests directly in Solidity. This is less flexible and sometimes more verbose than writing tests in the harness language, but the lack of a context switch means makes writing unit tests more pleasant for the developer.
+Dapple provides a VM test harness so you can write your tests directly in Solidity. This is less flexible and sometimes more verbose than writing tests in the harness language, but the lack of a context means makes writing unit tests more pleasant for the developer.
 
 Suppose you want to test this contract:
 
@@ -57,6 +57,6 @@ contract MyRegistryTest is Test {
 
 Further docs:
 
-[Testing Exceptions](https://github.com/nexusdev/dapple/doc/test_errors.md)
-[Testing Events](https://github.com/nexusdev/dapple/doc/test_events.md)
+[Testing Exceptions](https://github.com/nexusdev/dapple/blob/master/doc/test_errors.md)
+[Testing Events](https://github.com/nexusdev/dapple/blog/master/doc/test_events.md)
 
diff --git a/doc/test_errors.md b/doc/test_errors.md
@@ -1,5 +1,5 @@
 ## Test Errors
-This test feature captures thrown Errors of a transaction.
+This test feature captures thrown Errors (VM exceptions) of a transaction.
 All test functions which are starting with `testThrow`, `testFail` or `testError`
 are expected to crash: a `throw;` is expected somewhere in the scenario.
 
@@ -24,7 +24,7 @@ contract Contract {
 
 The following shows a passing test, because an expected throw actually happens:
 ```
-contract Tester is Test {
+contract MyTest is Test {
   function testThrow() {
     Contract target = new Contract();
     target.crash();
@@ -36,7 +36,7 @@ contract Tester is Test {
 
 The following test fails, because the function name has a **wrong prefix**:
 ```
-contract Tester is Test {
+contract MyTest is Test {
   function testCrash() {
     Contract target = new Contract();
     target.crash();
@@ -46,7 +46,7 @@ contract Tester is Test {
 
 The following test fails, because **no expected** throw happens:
 ```
-contract Tester is Test {
+contract MyTest is Test {
   function testError() {
     Contract target = new Contract();
     target.passing();

diff --git a/doc/test_events.md b/doc/test_events.md
@@ -35,7 +35,7 @@ contract `EventDefnitons`.
 ##### passing example
 The following shows a passing test:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]
 
@@ -53,7 +53,7 @@ contract Tester is Test, EventDefinitions {
 ##### failing examples
 The following test will fail because of the wrong **order** of the events:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]
 
@@ -70,7 +70,7 @@ contract Tester is Test, EventDefinitions {
 
 The following test will fail because of the wrong **type** of the events:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]
 
@@ -87,7 +87,7 @@ contract Tester is Test, EventDefinitions {
 
 The following test will fail because of the wrong **content** of the events:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]
 
@@ -104,7 +104,7 @@ contract Tester is Test, EventDefinitions {
 
 The following test will fail because an **unexpected** event is emited:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]
 
@@ -120,7 +120,7 @@ contract Tester is Test, EventDefinitions {
 
 The following test will fail because an expected event is **not emited**:
 ```
-contract Tester is Test, EventDefinitions {
+contract MyTest is Test, EventDefinitions {
 
   [...]