Add extension documentation plugin, generate initial README

Author: mrerrormessage

BUILDING.md

@@ -0,0 +1,7 @@
+## Building
+
+Use the netlogo.jar.url environment variable to tell sbt which NetLogo.jar to compile against (defaults to NetLogo 5.3). For example:
+
+    sbt -Dnetlogo.jar.url=file:///path/to/NetLogo/target/NetLogo.jar package
+
+If compilation succeeds, `array.jar` will be created.

LICENSE.md

@@ -0,0 +1,5 @@
+## Terms of Use
+
+[![CC0](http://i.creativecommons.org/p/zero/1.0/88x31.png)](http://creativecommons.org/publicdomain/zero/1.0/)
+
+The NetLogo array extension is in the public domain.  To the extent possible under law, Uri Wilensky has waived all copyright and related or neighboring rights.

README.md

@@ -1,10 +1,5 @@
-# NetLogo array extension
 
-This package contains the NetLogo array extension.
-
-## Using
-
-This extension is pre-installed in NetLogo. For instructions on using it, or for more information about NetLogo extensions, see the NetLogo User Manual.
+# NetLogo Array Extension
 
 ## Building
 
@@ -14,6 +9,96 @@ Use the netlogo.jar.url environment variable to tell sbt which NetLogo.jar to co
 
 If compilation succeeds, `array.jar` will be created.
 
+## Using
+
+The array extension is pre-installed in NetLogo.
+
+To use the array extension in your model, add a line to the top of your Code tab:
+
+```
+extensions [array]
+```
+
+If your model already uses other extensions, then it already has an
+`extensions` line in it, so just add `array` to the list.
+
+For more information on using NetLogo extensions,
+see the [Extensions Guide](http://ccl.northwestern.edu/netlogo/docs/extensions.html)
+
+### When to Use
+
+In general, anything you can do with an array in NetLogo, you could
+also just use a list for. But you may want to consider using an array
+instead for speed reasons. Lists and arrays have different performance
+ characteristics, so you may be able to make your model run faster by
+selecting the appropriate data structure.
+
+Arrays are useful when you need a collection of values whose size is
+fixed. You can quickly access or alter any item in an array if you
+know its position.
+
+Unlike NetLogo's lists and strings, arrays are "mutable".
+That means that you can actually modify them directly,
+rather than constructing an altered copy as with lists. If
+the array is used in more than one place in your code, any
+changes you make will show up everywhere. It's tricky to write
+code involving mutable structures and it's easy to make subtle
+errors or get surprising results, so we suggest sticking with lists
+and strings unless you're certain you want and need mutability.
+
+### Example use of Array Extension
+
+```NetLogo
+let a array:from-list n-values 5 [0]
+print a
+=> {{array: 0 0 0 0 0}}
+print array:length a
+=> 5
+foreach n-values 5 [ [i] -> i ] [ [i] -> array:set a i i * i ]
+print a
+=> {{array: 0 1 4 9 16}}
+print array:item a 0
+=> 0
+print array:item a 3
+=> 9
+array:set a 3 50
+print a
+=> {{array: 0 1 4 50 16}}
+```
+
+## Primitives
+
+
+### `array:from-list`
+
+Reports a new array containing the same items in the same order as the input list.
+
+
+### `array:item`
+
+Reports the item in the given array with the given index (ranging from zero to the length of the array minus one).
+
+
+### `array:set`
+
+
+Sets the item in the given array with the given index (ranging from zero to the length of the array minus one) to the given value.
+
+Note that unlike the `replace-item` primitive for lists, a new array is not created.
+The given array is actually modified.
+
+
+
+### `array:length`
+
+Reports the length of the given array, that is, the number of items in the array.
+
+
+### `array:to-list`
+
+Reports a new list containing the same items in the same order as the given array.
+
+
 ## Terms of Use
 
 [![CC0](http://i.creativecommons.org/p/zero/1.0/88x31.png)](http://creativecommons.org/publicdomain/zero/1.0/)

USING.md

@@ -0,0 +1,56 @@
+## Using
+
+The array extension is pre-installed in NetLogo.
+
+To use the array extension in your model, add a line to the top of your Code tab:
+
+```
+extensions [array]
+```
+
+If your model already uses other extensions, then it already has an
+`extensions` line in it, so just add `array` to the list.
+
+For more information on using NetLogo extensions,
+see the [Extensions Guide](http://ccl.northwestern.edu/netlogo/docs/extensions.html)
+
+### When to Use
+
+In general, anything you can do with an array in NetLogo, you could
+also just use a list for. But you may want to consider using an array
+instead for speed reasons. Lists and arrays have different performance
+ characteristics, so you may be able to make your model run faster by
+selecting the appropriate data structure.
+
+Arrays are useful when you need a collection of values whose size is
+fixed. You can quickly access or alter any item in an array if you
+know its position.
+
+Unlike NetLogo's lists and strings, arrays are "mutable".
+That means that you can actually modify them directly,
+rather than constructing an altered copy as with lists. If
+the array is used in more than one place in your code, any
+changes you make will show up everywhere. It's tricky to write
+code involving mutable structures and it's easy to make subtle
+errors or get surprising results, so we suggest sticking with lists
+and strings unless you're certain you want and need mutability.
+
+### Example use of Array Extension
+
+```NetLogo
+let a array:from-list n-values 5 [0]
+print a
+=> {{array: 0 0 0 0 0}}
+print array:length a
+=> 5
+foreach n-values 5 [ [i] -> i ] [ [i] -> array:set a i i * i ]
+print a
+=> {{array: 0 1 4 9 16}}
+print array:item a 0
+=> 0
+print array:item a 3
+=> 9
+array:set a 3 50
+print a
+=> {{array: 0 1 4 50 16}}
+```

build.sbt

@@ -1,4 +1,4 @@
-enablePlugins(org.nlogo.build.NetLogoExtension)
+enablePlugins(org.nlogo.build.NetLogoExtension, org.nlogo.build.ExtensionDocumentationPlugin)
 
 javaSource in Compile <<= baseDirectory(_ / "src")
 

documentation.conf

@@ -0,0 +1,63 @@
+extensionName = "array"
+markdownTemplate = """
+# NetLogo Array Extension
+
+{{#include}}BUILDING.md{{/include}}
+
+{{#include}}USING.md{{/include}}
+
+## Primitives
+
+{{#allPrimitives}}
+{{{.}}}
+{{/allPrimitives}}
+
+{{#include}}LICENSE.md{{/include}}
+"""
+primTemplate = """
+### `{{name}}`
+
+{{{description}}}
+"""
+filesToIncludeInManual = [ "BUILDING.md", "USING.md", "primitives" ]
+primitives = [
+  {
+    name: from-list,
+    type: reporter,
+    returns: array,
+    arguments: [ { type: list } ],
+    description: "Reports a new array containing the same items in the same order as the input list."
+  },
+  {
+    name: item,
+    type: reporter,
+    returns: anything,
+    arguments: [ { type: array }, { name: index, type: number } ],
+    description: "Reports the item in the given array with the given index (ranging from zero to the length of the array minus one)."
+  },
+  {
+    name: set,
+    type: command,
+    arguments: [ { type: array }, { name: index, type: number }, { name: value, type: anything } ],
+    description: """
+Sets the item in the given array with the given index (ranging from zero to the length of the array minus one) to the given value.
+
+Note that unlike the `replace-item` primitive for lists, a new array is not created.
+The given array is actually modified.
+"""
+  },
+  {
+    name: length,
+    type: reporter,
+    returns: number,
+    arguments: [ { type: array } ],
+    description: "Reports the length of the given array, that is, the number of items in the array."
+  },
+  {
+    name: to-list,
+    type: reporter,
+    returns: list,
+    arguments: [ { type: array } ],
+    description: "Reports a new list containing the same items in the same order as the given array."
+  }
+]

project/plugins.sbt

@@ -4,3 +4,4 @@ resolvers += Resolver.url(
     Resolver.ivyStylePatterns)
 
 addSbtPlugin("org.nlogo" % "netlogo-extension-plugin" % "3.0")
+addSbtPlugin("org.nlogo" % "netlogo-extension-documentation" % "0.5")