Merge pull request #28 from gravitystorm/docs
authorRichard Fairhurst <richard@systemeD.net>
Sun, 4 Mar 2012 14:32:54 +0000 (06:32 -0800)
committerRichard Fairhurst <richard@systemeD.net>
Sun, 4 Mar 2012 14:32:54 +0000 (06:32 -0800)
Docs

README.txt
build.xml
net/systemeD/halcyon/DebugURLRequest.as
net/systemeD/halcyon/JSController.as
net/systemeD/halcyon/MapEvent.as
net/systemeD/halcyon/styleparser/RuleSet.as
net/systemeD/potlatch2/TagViewer.mxml
net/systemeD/potlatch2/help/VideoPlayer.mxml
net/systemeD/potlatch2/mapfeatures/editors/RelationMemberEditorFactory.as
net/systemeD/potlatch2/panels/BackgroundMergePanel.mxml
net/systemeD/potlatch2/panels/BackgroundPanel.mxml

index dabfc42ada5060d4480c384d5ca769390c3e3ea6..492bb995caaf7a1abecc975448d503e59a27fd19 100644 (file)
@@ -12,7 +12,7 @@ Many icons used in halcyon/potlatch2 are based on the awesome CC0-licensed SJJB
 
 * Flex SDK 4.5
 ** Product page: http://www.adobe.com/products/flex/ 
-** Flex 4 Download page: http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4 (free, OS X/Windows/Linux)
+** Flex 4.5 Download page: http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4.5 (free, OS X/Windows/Linux)
 * AS3 docs - http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/
 * Flash debug player - http://www.adobe.com/support/flashplayer/downloads.html
 * Basically you might as well just sell your soul to Adobe
index 179ca4e63d1b46383b8b67e5c40f205c3afb7fb4..7b9ec07688e90108f2076f03ff1a321af5fce6b4 100644 (file)
--- a/build.xml
+++ b/build.xml
   <!-- note that there's an asdoc target in Flex 4, if/when we move to that -->
   <target name="docs" depends="manifests,makeLocalesList">
     <exec executable="${ASDOC}" failonerror="true">
-      <arg line="-source-path ."/>
-      <arg line="-doc-sources net/systemeD/"/>
+      <arg line="-source-path=."/>
+      <arg line="-doc-sources=net/systemeD/"/>
       <arg line="-external-library-path=lib/"/>
       <arg line="-external-library-path=${FLEX_HOME}/frameworks/libs/"/>
       <arg line="-external-library-path=${FLEX_HOME}/frameworks/libs/player/10.2/"/>
       <arg line="-lenient"/>
-      <arg line="-target-player 10.2.0"/>
-      <arg line="-exclude-classes ${org_classes} ${it_classes} ${hxasm_classes} ${com_classes}"/>
-      <arg line="-output resources/docs/"/>
-      <arg line="-window-title 'Halcyon and Potlatch2 Developer documentation'" />
-      <arg line="-main-title 'Halcyon and Potlatch2 Developer documentation'" />
-      <arg line="-footer 'Found an error? Help us fix it. http://wiki.openstreetmap.org/wiki/Potlatch2'"/>
+      <arg line="-target-player=10.2.0"/>
+      <arg line="-exclude-classes=${org_classes},${it_classes},${hxasm_classes},${com_classes}"/>
+      <arg line="-output=resources/docs/"/>
+      <arg line="-window-title='Halcyon and Potlatch2 Developer documentation'" />
+      <arg line="-main-title='Halcyon and Potlatch2 Developer documentation'" />
+      <arg line="-footer='Found an error? Help us fix it. http://wiki.openstreetmap.org/wiki/Potlatch2'"/>
       <arg line="-package net.systemeD.controls 'Custom-built controls used in Potlatch2'" />
       <arg line="-package net.systemeD.halcyon 'The AS3 rendering library'" />
       <arg line="-package net.systemeD.halcyon.connection 'The connection to the main OSM server, and the entities'" />
@@ -94,9 +94,8 @@
       <arg line="-package net.systemeD.potlatch2.tools 'Data manipulation tools'" />
       <arg line="-package net.systemeD.potlatch2.utils 'Data loading utilities'" />
       
-      <arg line="-left-frameset-width 300" />
-      <arg line="-locale=${locales.list}" />
-      <arg line="-allow-source-path-overlap true" />
+      <arg line="-left-frameset-width=300" />
+      <arg line="-allow-source-path-overlap=true" />
     </exec>
   </target>
 
 
         <fileset id="com_sources" dir="${basedir}/com/" />
         <!-- convert the names of excluded classes to packages with class names -->
-        <pathconvert property="com_classes" pathsep=" " refid="com_sources">
+        <pathconvert property="com_classes" pathsep="," refid="com_sources">
                 <chainedmapper>
                         <globmapper from="${basedir}/*" to="*"/>
                         <mapper type="package" from="*.as" to="*"/>
         <!-- Get the list of all files in the org directory -->
         <fileset id="org_sources" dir="${basedir}/org/" />
         <!-- convert the names of excluded classes to packages with class names -->
-        <pathconvert property="org_classes" pathsep=" " refid="org_sources">
+        <pathconvert property="org_classes" pathsep="," refid="org_sources">
                 <chainedmapper>
                         <globmapper from="${basedir}/*" to="*"/>
                         <mapper type="package" from="*.as" to="*"/>
 
         <fileset id="it_sources" dir="${basedir}/it/" />
         <!-- convert the names of excluded classes to packages with class names -->
-        <pathconvert property="it_classes" pathsep=" " refid="it_sources">
+        <pathconvert property="it_classes" pathsep="," refid="it_sources">
                 <chainedmapper>
                         <globmapper from="${basedir}/*" to="*"/>
                         <mapper type="package" from="*.as" to="*"/>
 
         <fileset id="hxasm_sources" dir="${basedir}/hxasm/" />
         <!-- convert the names of excluded classes to packages with class names -->
-        <pathconvert property="hxasm_classes" pathsep=" " refid="hxasm_sources">
+        <pathconvert property="hxasm_classes" pathsep="," refid="hxasm_sources">
                 <chainedmapper>
                         <globmapper from="${basedir}/*" to="*"/>
                         <mapper type="package" from="*.as" to="*"/>
index 8aa038bb2a349fbaded354ad1709ef1ca5811d1a..7bbf018dda90677f8eb4c7796453f17d5aee83d9 100644 (file)
@@ -1,24 +1,22 @@
 package net.systemeD.halcyon {
 
-       /*
-               === DebugURLRequest ===
-
-               If nocache has been set to 'true' via FlashVars, this will make the URLRequest using 
-               POST rather than GET - thereby preventing FP from caching it
-               (see http://www.ultrashock.com/forums/actionscript/force-reload-files-only-using-as3-123408.html).
-               
-               Sadly we can't just subclass URLRequest, which is defined as final. So you need to create your 
-               new DebugURLRequest, then refer to its .request property.
-               
-               We use an evil Global because we don't know where loaderInfo.parameters will be.
-
-       */
-
        import flash.net.URLRequest;
        import flash.net.URLRequestMethod;
        import flash.system.Capabilities;
        import net.systemeD.halcyon.Globals;
 
+    /**
+    * If nocache has been set to 'true' via FlashVars, this will make the URLRequest using
+    * POST rather than GET - thereby preventing FP from caching it.
+    *
+    * <p>Sadly we can't just subclass URLRequest, which is defined as final. So you need to create your
+    * new DebugURLRequest, then refer to its .request property.</p>
+    *
+    * <p>We use an evil Global because we don't know where loaderInfo.parameters will be.</p>
+    *
+    * @see http://www.ultrashock.com/forums/actionscript/force-reload-files-only-using-as3-123408.html
+    */
+
        public class DebugURLRequest {
 
                public var request:URLRequest;
index 81a2419680ea2a22e67de2b584b030dd67d9e79c..294f9d946d966c159bd1a553bed4fb1f92511444 100644 (file)
@@ -3,14 +3,19 @@ package net.systemeD.halcyon {
        import flash.events.*;
     import flash.external.ExternalInterface;
 
-       /* JSController provides an interface for Halcyon to call the enclosing page, via JavaScript
-         */
+       /**
+       * JSController provides an interface for Halcyon to call the enclosing page, via JavaScript.
+       */
 
     public class JSController implements MapController {
 
         private var map:Map;
-               private var jsresponder:String;                                 // JavaScript function called when user clicks
+               private var jsresponder:String;
 
+        /**
+        * @param map
+        * @param jsresponder JavaScript function called when user clicks
+        */
         public function JSController(map:Map, jsresponder:String) {
             this.map = map;
             this.jsresponder = jsresponder;
index 3dfeeba14dc60db333110927f5334404a23b8196..907d6cf5a80c26ed1885872a57fba7a4c43f5613 100644 (file)
@@ -17,7 +17,7 @@ package net.systemeD.halcyon {
                public static const NUDGE_BACKGROUND:String = "nudge_background";
         /** Map has been created and is ready, although data is not yet downloaded. */
         public static const INITIALISED:String = "initialized";
-               /** Backrgound imagery has changed to one with attribution that must not be obscured. */
+               /** Background imagery has changed to one with attribution that must not be obscured. */
                public static const BUMP:String = "bump";
                public static const MOUSE_MOVE:String="mouse_move";
                public static const ERROR:String = "error";                             // ** FIXME - this should be a dedicated ErrorEvent class
index d26d68e6de7b0316d381696ec7ebac7dbe56bc42..6a8d6a015fef1dda52b38a08015078c7a0bf23f5 100644 (file)
@@ -9,13 +9,15 @@ package net.systemeD.halcyon.styleparser {
     import net.systemeD.halcyon.ImageBank;
 
     import net.systemeD.halcyon.connection.*;
-       
-       /** A complete stylesheet, as loaded from a MapCSS file. It contains all selectors, declarations, 
-               and embedded images.                                                                                                                                                            </p><p>
-               
-               The RuleSet class has two principal methods: getStyles, which calculates the styles that apply
-               to an entity (returned as a StyleList); and parse, which parses a MapCSS stylesheet into
-               a complete RuleSet. */
+
+    /**
+    * A complete stylesheet, as loaded from a MapCSS file. It contains all selectors, declarations,
+    * and embedded images.
+    *
+    * <p>The RuleSet class has two principal methods: getStyles, which calculates the styles that apply
+    * to an entity (returned as a StyleList); and parse, which parses a MapCSS stylesheet into
+    * a complete RuleSet.</p>
+    */
 
        public class RuleSet {
 
index dbdc7f335dff88cc6d2f651d22ea8684449b92de..a2cbc157b3e66c768f8803f2203806e119746735 100644 (file)
@@ -1,4 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!---
+  The TagViewer is the container for the entire sidebar. It has a number of components, and subpanels, in a ViewStack that change
+  depending on what is selected, i.e. the ControllerState.
+
+  @see net.systemeD.potlatch2.controller.ControllerState
+    -->
 <mx:VBox
     xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:mx="library://ns.adobe.com/flex/mx"
index 33c720833a80d84f1d5d95ba9360929783a5c90a..4553ddabfa9dcd1f91b44ab1cc4f793785adf355 100644 (file)
@@ -1,4 +1,20 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!---
+    VideoPlayer component for P2 help dialog.
+    Embed like this:
+
+    <listing>
+    &lt;help:VideoPlayer width="400" height="300"
+        file="videos/test.flv"
+        previewImage="videos/test_preview.png" /&gt;
+    </listing>
+
+    <p>previewImage is the image that will be shown in the video pane
+    before the user clicks 'play' - usually a still of the first frame
+    of the video. (This means the video file won't be downloaded unless
+    the user actually wants it.)</p>
+
+    -->
 <mx:VBox
     xmlns:fx="http://ns.adobe.com/mxml/2009"
     xmlns:mx="library://ns.adobe.com/flex/mx"
        <fx:Script>
                <![CDATA[ 
 
-                       /** VideoPlayer component for P2 help dialog.
-                               Embed like this:
-
-                               <help:VideoPlayer width="400" height="300" 
-                                       file="videos/test.flv" 
-                                       previewImage="videos/test_preview.png" />
-                                       
-                               previewImage is the image that will be shown in the video pane
-                               before the user clicks 'play' - usually a still of the first frame
-                               of the video. (This means the video file won't be downloaded unless 
-                               the user actually wants it.)
-                       */
-
                        [Bindable] public var file:String;
                        [Bindable] public var previewImage:String; 
                        private var wasPlaying:Boolean;
index 8aa73f4dfa0d290cd28190e5d12aed4eeaa42291..cc2b5ab35369229daf9a413a0012d7c8a8f8cf90 100644 (file)
@@ -6,12 +6,12 @@ package net.systemeD.potlatch2.mapfeatures.editors {
     import net.systemeD.potlatch2.mapfeatures.*;
 
        public class RelationMemberEditorFactory extends EditorFactory {
-           /** Contains "route"=["hiking","foot"] key/values. The <match> map_features tag is parsed here from
+           /** Contains "route"=["hiking","foot"] key/values. The &lt;match&gt; map_features tag is parsed here from
            * "hiking|foot" pipe-separated values. */
            private var _relationTagPatterns:Object;
                private var _role:String;
         
-        /** Constructs the editing panel for a relation(###), given its <relation> in map_features.xml */
+        /** Constructs the editing panel for a relation(###), given its &lt;relation&gt; in map_features.xml */
         public function RelationMemberEditorFactory(inputXML:XML) {
             super(inputXML);
             _relationTagPatterns = {};
index f22182355631d52855396f82cf3dfb1699a4779e..d8827f1a0e7d072d537ae33c0be212e98175de06 100644 (file)
@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
-
-<!--
-    Background Merge Panel
+<!---
+    The Background Merge Panel allows the tags from two features - one from
+    a read-only vector background layer, one from an editable layer - to be
+    compared. Tags are highlighted depending whether they match, and tags from
+    the background layer can be easily merged.
 -->
 
 <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" height="100%">
       private var backgroundEntity:Entity;
       private var tagDataProvider:ArrayCollection;
 
+      /**
+      * @param entities The two entities that are being compared. One should be from a background layer, but the
+      *                 order is not important.
+      */
       public function init(entities:Array):void {
           if ( tagDataProvider == null ) {
               tagDataProvider = new ArrayCollection();
           updateTagDataProvider();
       }
 
+      /**
+      * Should the button for merging tags be shown?
+      *
+      * @param b The tag value for the background entity
+      * @param e The tag value for the editable entity
+      */
       public function buttonVisible(b:String, e:String):Boolean {
           if (b != null && b != e) {
               return true;
           return false;
       }
 
+      /**
+      * Merge the data for the given key. Results in the value being copied to the editable entity, using the
+      * global undo stack.
+      *
+      * @param key The tag key to be merged.
+      */
       public function mergeForKey(key:String):void {
           editableEntity.setTag(key, backgroundEntity.getTag(key), MainUndoStack.getGlobalStack().addAction);
       }
 
-      // Don't call this for things you don't want coloured in. Like for empty tags.
+      /**
+      * Figure out an appropriate background color for the row. Don't call this for things you don't want coloured in. Like for empty tags.
+      *
+      * @param i The row index in the tagDataProvider
+      * @return The colour to be used as the background of the field
+      */
       public function getColorFor(i:int):int {
           if (tagDataProvider[i].e == tagDataProvider[i].b) {
               return 0xDDFFDD; // matching, green
index 2895e75560c87703e5165b7d8d8c1e110a1d2492..b6c9348c1c68a0efc4c346717728fbae2eab2783 100644 (file)
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-
-<!--
-    Background Panel
+<!---
+    The Background Panel displays details about the background feature selected. It is currently only used
+    by the SnapshotConnection, and so has functionality to allow marking features as "complete".
 -->
 
 <mx:VBox