Merge pull request #621 from pulsar-edit/minor-docs-updates

Small Update to Docs

docs/README.md

@@ -1,14 +1,18 @@
-# Atom Docs
+# Pulsar Docs
 
 ![Atom](https://cloud.githubusercontent.com/assets/72919/2874231/3af1db48-d3dd-11e3-98dc-6066f8bc766f.png)
 
-Most of the Atom user and developer documentation is contained in the [Atom Flight Manual](https://github.com/atom/flight-manual.atom.io).
+Most of the Pulsar/Atom user and developer documentation is contained on the [Pulsar Website](https://pulsar-edit.dev/docs/launch-manual/).
+
+While the Pulsar website does not yet have the Pulsar API documentation, this is partially available within [Pulsar API Documentation](./Pulsar-API-Documentation.md) or otherwise the original docs are available from community members [here](https://atom-flight-manual-archive.github.io/).
+
+There is also general guidance on the internal [stucture and behavior](./architecture/README.md) of Pulsar available.
 
 ## Build documentation
 
 Instructions for building Atom on various platforms from source.
 
-* Moved to [the Flight Manual](https://flight-manual.atom.io/hacking-atom/sections/hacking-on-atom-core/)
+* Moved to [the Flight Manual](https://pulsar-edit.dev/docs/launch-manual/sections/core-hacking/)
     * Linux
     * macOS
     * Windows
@@ -16,5 +20,3 @@ Instructions for building Atom on various platforms from source.
 ## Other documentation
 
 [Native Profiling on macOS](./native-profiling.md)
-
-The other documentation that was listed here previously has been moved to [the Flight Manual](https://flight-manual.atom.io).

docs/architecture/README.md

@@ -0,0 +1,10 @@
+# Pulsar Architecture
+
+This directory contains a collection of files and diagrams, that aim to easily explain some of the core components or behaviors of Pulsar.
+
+Remember that keeping this charts up to date is best effort, and the age of these files should be taken into consideration.
+
+## Contents
+  - [Startup Overview](./overview.md)
+  - ['The World'](./the-world.md)
+  - [Package Preload](./package-preload.md)

docs/architecture/overview.md

@@ -0,0 +1,169 @@
+# Pulsar's High Level Startup Overview
+
+It's no secret that Pulsar since inherited from Atom, is a big and complex application.
+
+With many discrete, moving aspects, that not all developers have a concrete grasp on.
+The goal of this document is to make the architecture of Pulsar, as well as the logical flow
+more understandable and approachable.
+
+This will be accomplished through a series of illustrations detailing the functional decomposition and detailed logical flow of Pulsar and it's parts, as well as lists of what's accomplished in each part.
+
+This document is aimed at those roughly familiar with the large scale goals and features of Pulsar, as well as those with a basic understanding of the package model used to power much of Pulsar's functionality.
+
+![Pulsar Overview MermaidJS Image](./assets/pulsar-overview.svg "Pulsar Overview")
+
+<details>
+<summary>
+MermaidJS to create image above
+</summary>
+
+```
+flowchart TD
+    id1("`Initialization
+        *./src/main-process/main.js*`") --> id2("`Startup
+                                            *./src/main-process/start.js*`")
+    id2 --> id3("`Main Process Tests`")
+    id2 --> id4("`Application Startup
+                 *./src/main-process/atom-application.js*`")
+    id2 --> id5("`Startup w/ Squirrel
+                *./src/main-process/squirrel-update.js*`")
+    id4 --> id6("`Test Runner
+                *./src/initialize-test-window.js*`")
+    id4 --> id7("`Initialize Application Window
+                *./src/initialize-application-window.js*`")
+    id7 --> id9("`'The World'
+                *./src/atom-environment.js*`")
+    id7 --> id10("`ApplicationDelegate
+                *./src/application-delegate.js*`")
+    id7 --> id8("`Clipboard
+                *./src/clipboard.js*`")
+    id8 --> id9
+    id10 --> id9
+```
+
+</details>
+
+---
+
+To further outline what occurs in the steps above:
+
+## Initialization
+
+Startup of Pulsar occurs within `./src/main-process/main.js`.
+
+Which Determines:
+  - `resourcePath`
+  - `devResourcePath`
+  - `stableResourcePath`
+  - `defaultRepositoryPath`
+
+Which Sets:
+  - Application Start Time
+
+Which Does:
+  - Initializes Startup of `./src/main-process/start.js`
+
+## Startup
+
+The more general startup handling of Pulsar occurs within `./src/main-process/start.js`.
+
+Which Sets:
+  - Shell Start Time
+  - `app.allowRendererProcessReuse`: `false`
+  - `app.commandLine.appendSwitch('enable-experimental-web-platform-features')`
+  - `app.commandLine.appendSwitch('force-color-profile', config.get('core.colorProfile'))`
+  - `app.setAppUserModelId()`
+  - `app.on('open-file', $)`
+  - `app.on('open-url', $)`
+
+Which Does:
+  - Normalizes the `resourcePath` and `devResourcePath`
+  - Uses `Config` to locate and read the config file
+  - `atomPaths.setAtomHome()`
+  - `atomPaths.setUserData()`
+  - May defer to `./src/main-process/squirrel-update.js` to startup if on Windows
+  - May defer to `./spec/main-process/mocha-test-runner.js` to startup main process tests
+  - May call `.open()` on `./src/main-process/atom-application.js`
+
+## Application Startup
+
+The proper startup of the Pulsar Application occurs within `./src/main-process/atom-application.js`.
+
+Which Sets:
+  - `APPLICATION_STATE_VERSION`
+  - Global `atomApplication`
+
+Which Does:
+  - Does setup of the application socket
+  - Handles deprecated benchmark startup
+  - Ensures to return a new instance of `AtomApplication`
+  - Registers basic application commands
+  - Initializes:
+    * `ApplicationMenu`
+    * `AtomProtocolHandler`
+    * `WindowStack`
+    * `FileRecoveryService`
+    * `Config`
+    * `StorageFolder`
+    * `AutoUpdateManager`
+  - May startup the package test runner
+  - May quit if asked to startup in benchmark mode
+  - May open previously opened files/folders
+  - May open new instance of Pulsar
+
+## Initialize Application Window
+
+Begins initialization of an individual Pulsar window, occurs within `./src/initialize-application-window.js`.
+
+Which Determines:
+
+Which Sets:
+  - Sets the `global.atom` to a new instance of `AtomEnvironment`
+
+Which Does:
+  - triggers `.preloadPackages()`
+  - Initializes:
+    * Clipboard
+    * AtomEnvironment
+    * ApplicationDelegate
+
+## 'The World'
+
+'The World' refers to being within the Pulsar application, most of the application occurs within here.
+This code lives within `./src/atom-environment.js`.
+
+An important note about being initialized within the world, there is no access to the `atom`
+global, until the initial constructor completes processing. Meaning great care must be taken
+to ensure if `atom` is available within the initialized modules.
+
+Which Sets:
+  - `AtomEnvironment.version`: `1` | Possibly a reference to `APPLICATION_STATE_VERSION`?
+  - `AtomEnvironment.saveStateDebounceInterval`: `1000`
+
+Which Does:
+  - Initializes:
+    * Clipboard | Inherited from 'Initialize Application Window'
+    * ApplicationDelegate | Inherited from 'Initialize Application Window'
+    * DeserializerManager
+    * ViewRegistry
+    * NotificationManager
+    * StateStore
+    * Config
+    * KeymapManager
+    * TooltipManager
+    * CommandRegistry
+    * URIHandlerRegistry
+    * GrammarRegistry
+    * StyleManager
+    * PackageManager
+    * ThemeManager
+    * MenuManager
+    * ContextMenuManager
+    * Project
+    * CommandInstaller
+    * ProtocolHandlerInstaller
+    * TextEditorRegistry
+    * Workspace
+    * AutoUpdateManager
+    * WindowEventHandler
+    * HistoryManager

docs/architecture/package-preload.md

@@ -0,0 +1,66 @@
+# Package Preload
+
+Pulsar's packages are preloaded, very early on within the startup cycle of Pulsar.
+
+As it's called immediatly after the `atom` global is initialized, it's important to understand what steps occur during preloading, and what package's are affected.
+
+![Package Preload Overview](./assets/package-preload.svg "Package Preload Overview")
+
+---
+
+<details>
+<summary>
+MermaidJS to create image above
+</summary>
+
+```
+flowchart TD
+    iaw["`
+        initialize-application-window.js
+        Called right after global 'atom' is set
+    `"] -->
+    ae["`
+        AtomEnvironment
+        .preloadPackages()
+    `"] -->
+    pl1["preloadPackages()"] -->|if in packageCache| sg1
+
+    subgraph sg1
+    direction LR
+    pl2["preloadPackage()"]
+    pl2 -->|"call .preload()"| tp1["new ThemePackage"]
+    pl2 -->|"call .preload()"| p1["new Package"]
+
+    p1 --> p1Pre["`
+        this.preload() call:
+        Does more than advertised here
+    `"]
+
+    p1Pre --> lk1[".loadKeymaps()"]
+    lk1 --> pcRead1["`Read from packagesCache:
+        If bundled package && in packagesCache`"]
+    lk1 --> fileRead1["`Read from file:
+        If !bundled || !in packagesCache`"]
+
+    p1Pre --> lm1[".loadMenus()"]
+    lm1 --> pcRead1
+    lm1 --> fileRead1
+
+    p1Pre --> acss[".activateCoreStartupServices()"]
+    p1Pre --> rmm[".requireMainModule()"]
+
+    acss --> rmm
+
+    p1Pre --> ls1[".loadSettings()"]
+    ls1 --> pcRead1
+    ls1 --> fileRead1
+
+    p1Pre --> ak1[".activateKeymaps()"]
+    p1Pre --> am1[".activateMenus()"]
+
+    tp1 --> tp1Pre[".preload()"]
+    tp1Pre --> csrol1[".reigsterConfigSchemaFromMetadata()"]
+    end
+```
+
+</details>

docs/architecture/the-world.md

@@ -0,0 +1,101 @@
+# 'The World'
+
+While it's difficult to convey the full scope of how Pulsar works internally, just like the previous page [`overview.md`](./overview.md) detailed the general gist of how Pulsar starts up, this document provides a quick reference to how all the interal parts of Pulsar are connected.
+
+This document is not at all comprehensive, and must ensure to be continually updated. Additionally, this image does not track outside dependency usage, nor dependence on every single internal module. Focusing mostly on modules that are either required during initialization, or are referenced during the constructor of their respective class.
+
+<details>
+<summary>
+Details on the creation of this image
+</summary>
+
+This image has been created with Plant UML. A Live editor is available [here](https://www.plantuml.com/plantuml/uml).
+
+The code used to create this image:
+
+```uml
+@startwbs
+* Initialization
+** Startup
+***< Main Process Tests
+*** Startup w/ Squirrel
+***< Application Startup
+****< Test Runner
+**** Initialize Application Window
+***** 'The World'
+******< Config
+******* ScopeDescriptor
+****** KemapManager
+****** TolltipManager
+******* Tooltip
+******< CommandRegistry
+******< URIHandlerRegistry
+****** StyleManager
+******* createStylesElement
+******* DEPRECATED_SYNTAX_SELECTORS
+******< MenuManager
+******* MenuHelpers
+****** ContextMenuManager
+******* MenuHelpers
+******* sortMenuItems
+******< TextEditorRegistry
+******* TextEditor
+******* ScopeDescriptor
+****** HistoryManager
+******< DeserializerManager
+******< ViewRegistry
+****** NotificationManager
+******* Notification
+****** StateStore
+******< PackageManager
+******* Package
+******* ThemePackage
+******* ModuleCache
+****** ThemeManager
+******* LessCompileCache
+****** Project
+******* watchPath
+******* DefaultDirectoryProvider
+******* Model
+******* GitRepositoryProvider
+******< CommandInstaller
+******< ProtocolHandlerInstaller
+******< AutoUpdateManager
+******< WindowEventHandler
+******* listen
+******< GrammarRegistry
+*******< NodeTreeSitterLanguageMode
+******** TreeIndenter
+********< TextMateLanguageMode
+******** TokenizedLine
+********< ScopeDescriptor
+******** matcherForSelector
+********< Token
+******* WASMTreeSitterLanguageNode
+******** Parser
+******* TextMateLanguageMode
+******** TokenizedLine
+********< TokenIterator
+******** ScopeDescriptor
+********< NullGrammar
+*******< ScopeDescriptor
+******* Token
+****** Workspace
+******* DefaultDirectorySearcher
+*******< RipgrepDirectorySearcher
+******* WorkspaceCenter
+*******< createWorkspaceElement
+******* PanelContainer
+*******< StateStore
+******* TextEditor
+*******< Panel
+******* Task
+*******< Dock
+@endwbs
+```
+
+</details>
+
+---
+
+![Pulsar 'How Everything Connects' UML Image](./assets/how-everything-connects.svg "Pulsar 'How Everything Connects'")