docs: split usage and dev docs

src/common/README.md → doc/devdocs/common.md

@@ -1,6 +1,3 @@
-# Introduction
-The common lib, as the name suggests, contains code shared by multiple PowerToys components and modules.
-
 # Classes and structures
 
 #### class Animation: [header](./animation.h) [source](./animation.cpp)

doc/devdocs/modules/example_powertoy.md

@@ -0,0 +1,5 @@
+#### [`dllmain.cpp`](./dllmain.cpp)
+Contains DLL boilerplate code and implementation of the [PowerToys interface](/src/modules/interface/).
+
+#### [`trace.cpp`](./trace.cpp)
+Contains code for telemetry.

src/modules/interface/README.md → doc/devdocs/modules/interface.md

@@ -1,11 +1,4 @@
-# PowerToys Interface
-
-The PowerToys interface that each PowerToy must implement.
-See [`the example PowerToy`](/src/modules/example_powertoy) for a PowerToys module example that uses this interface.
-
-## Interface definition
-
-This is the interface definition:
+# Interface definition
 
 ```cpp
 class PowertoyModuleIface {
@@ -27,7 +20,7 @@ public:
 typedef PowertoyModuleIface* (__cdecl *powertoy_create_func)();
 ```
 
-### Runtime logic
+# Runtime logic
 
 The PowerToys runner will, for each PowerToy DLL:
   - load the DLL,
@@ -54,11 +47,11 @@ When terminating, the runner will:
   - unload the DLL.
 
 
-### Method definition
+## Method definition
 
 This section contains a more detailed description of each of the interface methods.
 
-#### powertoy_create_func
+### powertoy_create_func
 
 ```cpp
 typedef PowertoyModuleIface* (__cdecl *powertoy_create_func)()
@@ -86,7 +79,7 @@ ExamplePowertoy::ExamplePowertoy() {
 }
 ```
 
-#### get_name
+### get_name
 
 ```cpp
 virtual const wchar_t* get_name()
@@ -101,7 +94,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### get_events
+### get_events
 
 ```cpp
 virtual const wchar_t** get_events()
@@ -124,7 +117,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### get_config
+### get_config
 
 ```
 virtual bool get_config(wchar_t* buffer, int *buffer_size)
@@ -174,7 +167,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### set_config
+### set_config
 
 ```cpp
 virtual void set_config(const wchar_t* config)
@@ -207,7 +200,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### call_custom_action
+### call_custom_action
 
 ```cpp
   virtual void call_custom_action(const wchar_t* action)
@@ -241,7 +234,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### enable
+### enable
 
 ```cpp
   virtual void enable()
@@ -257,7 +250,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### disable
+### disable
 
 ```cpp
   virtual void disable()
@@ -273,7 +266,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-#### is_enabled
+### is_enabled
 
 ```cpp
   virtual bool is_enabled() = 0;
@@ -288,7 +281,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
     return m_enabled;
   }
 ```
-#### signal_event
+### signal_event
 
 ```cpp
   virtual intptr_t signal_event(const wchar_t* name, intptr_t data) = 0;
@@ -317,7 +310,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-### register_system_menu_helper
+## register_system_menu_helper
 
 ```cpp
   virtual void register_system_menu_helper(PowertoySystemMenuIface* helper) = 0;
@@ -327,7 +320,7 @@ Register helper class to handle all system menu items related actions. Creation,
 and all other actions taken on system menu item will be handled by provided class.
 Module will be informed when action is taken on any item created on request of the module.
 
-### signal_system_menu_action
+## signal_system_menu_action
 
 ```cpp
   virtual void signal_system_menu_action(const wchar_t* name) = 0;
@@ -336,7 +329,7 @@ Module will be informed when action is taken on any item created on request of t
 Runner invokes this API when action is taken on item created on request from the module.
 Item name is passed as an argument, so that module can distinguish between different menu items.
 
-#### destroy
+### destroy
 
 ```cpp
   virtual void destroy()
@@ -351,7 +344,7 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
   }
 ```
 
-### Powertoys system menu helper interface
+## Powertoys system menu helper interface
 
 Interface for helper class responsible for handling all system menu related actions.
 ```cpp
@@ -367,7 +360,7 @@ public:
 };
 ```
 
-### ItemInfo
+## ItemInfo
 
 ```cpp
   struct ItemInfo {
@@ -380,33 +373,33 @@ public:
 Structure containing all relevant information for system menu item: name (and hotkey if available), item
 status at creation (enabled/disabled) and whether check box will appear next to item name when action is taken.
 
-### SetConfiguration
+## SetConfiguration
 
 ```cpp
   virtual void SetConfiguration(PowertoyModuleIface* module, const std::vector<ItemInfo>& config) = 0;
 ```
 
 Module should use this interface to inform system menu helper class which custom system menu items to create.
 
-### ProcessSelectedItem
+## ProcessSelectedItem
 
 ```cpp
   virtual void ProcessSelectedItem(PowertoyModuleIface* module, HWND window, const wchar_t* itemName) = 0;
 ```
 
 Process action taken on specific system menu item.
 
-## Code organization
+# Code organization
 
-#### [`powertoy_module_interface.h`](./powertoy_module_interface.h)
+### [`powertoy_module_interface.h`](/src/modules/example_powertoy/powertoy_module_interface.h)
 Contains the PowerToys interface definition.
 
-### [`powertoy_system_menu.h`](./powertoy_system_module.h)
+### [`powertoy_system_menu.h`](/src/modules/example_powertoy/powertoy_system_module.h)
 Contains the PowerToys system menu helper interface definition.
 
-#### [`lowlevel_keyboard_event_data.h`](./lowlevel_keyboard_event_data.h)
+### [`lowlevel_keyboard_event_data.h`](/src/modules/example_powertoy/lowlevel_keyboard_event_data.h)
 Contains the `LowlevelKeyboardEvent` structure that's passed to `signal_event` for `ll_keyboard` events.
 
-#### [`win_hook_event_data.h`](./win_hook_event_data.h)
+### [`win_hook_event_data.h`](/src/modules/example_powertoy/win_hook_event_data.h)
 Contains the `WinHookEvent` structure that's passed to `signal_event` for `win_hook_event` events.
 

doc/devdocs/modules/shortcut_guide.md

@@ -0,0 +1,17 @@
+#### [`dllmain.cpp`](/src/modules/shortcut_guide/dllmain.cpp)
+Contains DLL boilerplate code.
+
+#### [`shortcut_guide.cpp`](/src/modules/shortcut_guide/shortcut_guide.cpp)
+Contains the module interface code. It initializes the settings values and the keyboard event listener.
+
+#### [`overlay_window.cpp`](/src/modules/shortcut_guide/overlay_window.cpp)
+Contains the code for loading the SVGs, creating and rendering of the overlay window.
+
+#### [`keyboard_state.cpp`](/src/modules/shortcut_guide/keyboard_state.cpp)
+Contains helper methods for checking the current state of the keyboard.
+
+#### [`target_state.cpp`](/src/modules/shortcut_guide/target_state.cpp)
+State machine that handles the keyboard events. It’s responsible for deciding when to show the overlay, when to suppress the Start menu (if the overlay is displayed long enough), etc.
+
+#### [`trace.cpp`](/src/modules/shortcut_guide/trace.cpp)
+Contains code for telemetry.

doc/devdocs/readme.md

@@ -0,0 +1,78 @@
+# Code Organization
+
+## Rules
+
+- **Follow the pattern of what you already see in the code**
+- Try to package new ideas/components into libraries that have nicely defined interfaces
+- Package new ideas into classes or refactor existing ideas into a class as you extend
+
+## Code Overview
+
+General project organization:
+
+#### The [`doc`](/doc) folder
+Documentation for the project, including a [coding guide](/doc/coding) and [design docs](/doc/specs).
+
+#### The [`installer`](/installer) folder
+Contains the source code of the PowerToys installer.
+
+#### The [`src`](/src) folder
+Contains the source code of the PowerToys runner and of all of the PowerToys modules. **This is where the most of the magic happens.**
+
+#### The [`tools`](/tools) folder
+Various tools used by PowerToys. Includes the Visual Studio 2019 project template for new PowerToys.
+
+# Implementation details
+
+### [`Runner`](/doc/devdocs/runner.md)
+The PowerToys Runner contains the project for the PowerToys.exe executable.
+It's responsible for:
+- Loading the individual PowerToys modules.
+- Passing registered events to the PowerToys.
+- Showing a system tray icon to manage the PowerToys.
+- Bridging between the PowerToys modules and the Settings editor.
+
+![Image of the tray icon](/doc/images/runner/tray.png)
+
+### [`Interface`](/doc/devdocs/modules/interface.md)
+Definition of the interface used by the [`runner`](/src/runner) to manage the PowerToys. All PowerToys must implement this interface.
+
+### [`Common`](/doc/devdocs/common.md)
+The common lib, as the name suggests, contains code shared by multiple PowerToys components and modules, e.g. [json parsing](/src/common/json.h) and [IPC primitives](/src/common/two_way_pipe_message_ipc.h).
+
+
+### [`Settings`](/doc/devdocs/settings.md)
+WebView project for editing the PowerToys settings.
+
+The html portion of the project that is shown in the WebView is contained in [`settings-html`](/src/settings/settings-heml).
+Instructions on how build a new version and update this project are in the [Web project for the Settings UI](./settings-web.md).
+
+While developing, it's possible to connect the WebView to the development server running in localhost by setting the `_DEBUG_WITH_LOCALHOST` flag to `1` and following the instructions near it in `./main.cpp`.
+
+### [`Settings-web`](/doc/devdocs/settings-web.md)
+This project generates the web UI shown in the [PowerToys Settings](/src/editor).
+It's a `ReactJS` project created using [UI Fabric](https://developer.microsoft.com/en-us/fabric#/).
+
+### [`FancyZones`](/doc/devdocs/modules/fancyzones.md)
+The FancyZones PowerToy that allows users to create custom zones on the screen, to which the windows will snap when moved.
+
+### [`PowerRename`](/doc/devdocs/modules/powerrename.md)
+PowerRename is a Windows Shell Context Menu Extension for advanced bulk renaming using simple search and replace or more powerful regular expression matching.
+
+### [`Shortcut Guide`](/doc/devdocs/modules/shortcut_guide.md)
+The Windows Shortcut Guide, displayed when the WinKey is held for some time.
+
+### _obsolete_ [`example_powertoy`](/doc/devdocs/modules/example_powertoy.md)
+An example PowerToy, that demonstrates how to create new ones. Please note, that this is going to become a Visual Studio project template soon.
+
+This PowerToy serves as a sample to show how to implement the [PowerToys interface](/src/modules/interface/) when creating a PowerToy. It also showcases the currently implemented settings.
+
+#### Options
+This module has a setting to serve as an example for each of the currently implemented settings property:
+  - BoolToggle property
+  - IntSpinner property
+  - String property
+  - ColorPicker property
+  - CustomAction property
+
+![Image of the Options](/doc/images/example_powertoy/settings.png)

src/runner/README.md → doc/devdocs/runner.md

@@ -1,18 +1,3 @@
-# PowerToys Runner
-
-# Introduction
-
-The PowerToys Runner contains the project for the PowerToys.exe executable.
-It's responsible for:
-- Loading the individual PowerToys modules.
-- Passing registered events to the PowerToys.
-- Showing a system tray icon to manage the PowerToys.
-- Bridging between the PowerToys modules and the Settings editor.
-
-![Image of the tray icon](/doc/images/runner/tray.png)
-
-# Code organization
-
 #### [`main.cpp`](./main.cpp)
 Contains the executable starting point, initialization code and the list of known PowerToys.
 

src/settings-web/README.md → doc/devdocs/settings-web.md

@@ -1,10 +1,3 @@
-# Web project for the Settings UI
-
-## Introduction
-
-This project generates the web UI shown in the [PowerToys Settings](/src/editor).
-It's a `ReactJS` project created using [UI Fabric](https://developer.microsoft.com/en-us/fabric#/).
-
 ## Build Commands
 
 Here are the commands to build and test this project:

doc/devdocs/settings.md

@@ -0,0 +1,8 @@
+#### [main.cpp](./main.cpp)
+Contains the main executable code, initializing and managing the Window containing the WebView and communication with the main PowerToys executable.
+
+#### [StreamURIResolverFromFile.cpp](./StreamURIResolverFromFile.cpp)
+Defines a class implementing `IUriToStreamResolver`. Allows the WebView to navigate to filesystem files in this Win32 project.
+
+#### [settings-html/](./settings-html/)
+Contains the assets file from building the [Web project for the Settings UI](../settings-web). It will be loaded by the WebView.