Add/improve documentation

Author: cycomachead

docs/API.md

@@ -10,54 +10,54 @@ Currently the API consists of the following methods:
 
 #### Navigate Scenes
 
-* IDE_Morph.prototype.getScenes()
-* IDE_Morph.prototype.getCurrentScene()
-* IDE_Morph.prototype.switchTo()
+* `IDE_Morph.prototype.getScenes()`
+* `IDE_Morph.prototype.getCurrentScene()`
+* `IDE_Morph.prototype.switchTo()`
 
 #### Control Processes
 
-* IDE_Morph.prototype.isRunning()
-* IDE_Morph.prototype.stop()
+* `IDE_Morph.prototype.isRunning()`
+* `IDE_Morph.prototype.stop()`
 
 #### Broadcast Messages (and optionally wait)
 
-* IDE_Morph.prototype.broadcast()
+* `IDE_Morph.prototype.broadcast()`
 
 #### Listen to Messages
 
-* IDE_Morph.prototype.addMessageListenerForAll()
-* IDE_Morph.prototype.addMessageListener()
-* IDE_Morph.prototype.getMessages()
+* `IDE_Morph.prototype.addMessageListenerForAll()`
+* `IDE_Morph.prototype.addMessageListener()`
+* `IDE_Morph.prototype.getMessages()`
 
 #### Access Global Variables
 
-* IDE_Morph.prototype.getVarNames()
-* IDE_Morph.prototype.getVar()
-* IDE_Morph.prototype.setVar()
+* `IDE_Morph.prototype.getVarNames()`
+* `IDE_Morph.prototype.getVar()`
+* `IDE_Morph.prototype.setVar()`
 
 #### Create and Modify Lists
 
-* IDE_Morph.prototype.newList()
+* `IDE_Morph.prototype.newList()`
 
 #### Access the Serialized Project
 
-* IDE_Morph.prototype.getProjectXML()
-* IDE_Morph.prototype.loadProjectXML()
-* IDE_Morph.prototype.unsavedChanges()
+* `IDE_Morph.prototype.getProjectXML()`
+* `IDE_Morph.prototype.loadProjectXML()`
+* `IDE_Morph.prototype.unsavedChanges()`
 
 #### Synchronize Scripts
 
-* IDE_Morph.prototype.getSpriteScriptsXML()
-* IDE_Morph.prototype.loadSpriteScriptsXML()
+* `IDE_Morph.prototype.getSpriteScriptsXML()`
+* `IDE_Morph.prototype.loadSpriteScriptsXML()`
 
 #### Highlight Blocks
 
-* IDE_Morph.prototype.flashSpriteScripts()
-* IDE_Morph.prototype.unflashSpriteScripts
+* `IDE_Morph.prototype.flashSpriteScripts()`
+* `IDE_Morph.prototype.unflashSpriteScripts`
 
 #### Set the Language
 
-* IDE_Morph.prototype.setTranslation()
+* `IDE_Morph.prototype.setTranslation()`
 
 ## Referencing the IDE
 

docs/Migrating.md

@@ -27,7 +27,7 @@ The second section is a recipe how to actually migrate your code. It's a list of
     - `silentSetWidth` => use `bounds.setWidth()` to avoid infinite recursion
     - `silentSetHeight` = use `bounds.setHeight()` to avoid infinite recursion
 * likewise "silent" parameters to functions are no longer needed and supported and should simply be removed
-* `cachedFullImage` has been removed and is no longer available (except internally for the HandMorph)

+* `cachedFullImage` has been removed and is no longer available (except internally for the HandMorph)
 * `cachedFullBounds` has been removed and is no longer available (except internally for the HandMorph)
 * `trackChanges` and other damage-list housekeeping tweaks are no longer needed and no longer supported, except for the Pen constructor's isWarped property and its methods, such as `startWarp()` and `endWarp()`.
 * Pen >> `wantsRedraw` is no longer needed and deprecated
@@ -40,7 +40,7 @@ The second section is a recipe how to actually migrate your code. It's a list of
 * `fullImageClassic()` => is now always just `fullImage()`
 * `keyboardReceiver` => `keyboardFocus`
 * keyboard navigation can be activated for any visible menu by pressing an arbitrary key
-* new `noDropShadow` property for Morphs that already have built-in shadows (Menus, SpeechBubbles)

+* new `noDropShadow` property for Morphs that already have built-in shadows (Menus, SpeechBubbles)
 * new `fullShadowSource` flag for Morphs, default is `true`, turn off (`false`) to only use the simple image instead of `fullImage()`
 
 ## Migrating Your Sources
@@ -53,9 +53,9 @@ Search your code for these words and replace them according to the instructions.
     - rename method definitions to `render`, notice that the first argument needs to be the 2D context, therefore remove the part in the code that makes a new canvas and queries its context.
     - factor out the parts of the code that determine and set the extent and add or arrange submorphs and move them into a - possibly new - method named `fixLayout()`
     - rename function calls to `drawNew()` to `fixLayout()` and/or `rerender()`, check whether the call is at all needed as it might be redundant in the new system
-* **wantsRedraw** => replace with `rerender()`

-* **noticesTransparentClick** => replace with `!isFreeForm`, use with caution, as free forms should also cache their image for performance reason, which in turn strains memory usage

-* **.image** => rename getters to `getImage()`, use with caution because of performance bottlenecks

+* **wantsRedraw** => replace with `rerender()`
+* **noticesTransparentClick** => replace with `!isFreeForm`, use with caution, as free forms should also cache their image for performance reason, which in turn strains memory usage
+* **.image** => rename getters to `getImage()`, use with caution because of performance bottlenecks
 * **cachedFullImage** => no longer supported, remove all references
 * **fullImageClassic** => rename method calls to just `fullImage()`
 * **silentSet**

docs/README.md

@@ -0,0 +1,43 @@
+# Snap<em>!</em> Development Documentation
+> last updated May 6, 2023.
+
+This guide is intended for _developers_ who want to ingrate Snap! into existing projects. Each of these guides is a breif introduction to maintaining an extension. The goal is to _minimize_ the amount of customizations you need to make to the Snap! source code, located in `src/`.
+
+**Before contributing source code modifications, please review [the contributations guide](./CONTRIBUTING.md) and get in touch!
+
+_Note:_ This document applies only to the Snap! IDE. The Snap!Cloud backend lives at [@snap-cloud/snapCloud](https://github.com/snap-cloud/snapCloud) on GitHub.
+
+## Guides
+
+There are many ways to build your own customized Snap! environments. Start in this order, with the least customizations.
+
+### Microworlds
+
+Microworlds are restricted Snap! environments, which hide blocks, and may change some settings that are saved with the project.
+
+Things you can save with the project:
+
+* Hiding Blocks
+* Single Palette Settings
+* Disable Click-to-Run
+* Disable Dragging Data
+
+_More coming soon!_
+
+### [Extensions.md](./Extensions.md)
+
+You can write JavaScript files which provide additional blocks, add interface elements, etc. These extensions are often packaged as a Snap! library.
+
+### [API.md](./API.md)
+
+The Snap! API can be used to embed or customize Snap! to be used in unique environments. You can check out the (work in progress) [Pyret example](../pyret/inline.html).
+
+### [Offline.md](./Offline.md)
+
+This describes how you can distribute Snap! to work offline.
+
+---
+
+### [Migrating.md](./Migrating.md)
+
+This describes the internal changes to the Morphic library. It is probably not useful unless you have made a fork of Snap!.