doc readme

Author: obfuscatedgenerated

src/api_docs/README.md

@@ -0,0 +1,44 @@
+# OllieOS API Documentation
+
+Welcome to the OllieOS Program API documentation.
+
+This document provides an overview of the APIs available to your program and their usage.
+
+## Categories
+
+### [Userspace API](./modules/Userspace.html)
+
+All programs have access to the Userspace API, providing limited access to the kernel but allowing interaction with the system.
+
+### [Kernel (Privileged) API](./modules/Kernel_(Privileged).html)
+
+Programs that start privileged, or successfully [request elevation](./interfaces/Userspace.UserspaceKernel.html#request_privilege-1), have access to the Kernel API, which provides full access to the system.
+
+This is a responsibility, and programs should only request elevation when absolutely necessary.
+
+### [Program Types](./modules/Program_Types.html)
+
+Additional information on the type assertions applied to define a program in OllieOS.
+
+## Example Program
+
+Here is a minimal example of how programs are structured in OllieOS, according to the [Program interface](./interfaces/Program_Types.Program.html):
+
+```ts
+import type { Program } from "ollieos/types";
+
+export default {
+    name: "hwpkg",
+    description: "Says hello to the world!",
+    usage_suffix: "",
+    arg_descriptions: {},
+    compat: "2.0.0",
+    main: async (data) => {
+        const { term } = data;
+
+        term.writeln("hello package!");
+
+        return 0;
+    }
+} as Program;
+```

src/api_docs/privileged.ts

@@ -5,6 +5,6 @@
 
 export type { Kernel } from "../kernel";
 export type { AbstractFileSystem } from "../kernel/filesystem";
-export type { ProcessManager, IPCManager, ProcessContext } from "../kernel/processes";
+export type { ProcessManager, ProcessContext, IPCManager } from "../kernel/processes";
 export type { ProgramRegistry } from "../kernel/prog_registry";
 export type { AbstractWindow, AbstractWindowManager } from "../kernel/windowing";

src/api_docs/types.ts

@@ -1,5 +1,6 @@
 /**
- * @module Types
+ * @module Program Types
+ * @description Type interfaces for the definition of program files.
  */
 
 export type {
@@ -9,7 +10,7 @@ export type {
     ArgDescriptions,
     CompletionGenerator,
     CompletionData,
-    ProgramRegistrant,
-    KeyEvent,
-    KeyEventHandler
+    PrivilegedProgram,
+    PrivilegedProgramMain,
+    PrivilegedProgramMainData
 } from "../types";

src/api_docs/userspace.ts

@@ -6,18 +6,19 @@
 export type {UserspaceKernel, SpawnResult, ParsedCommandLine} from "../kernel";
 export type {UserspaceFileSystem, FSEventType, FSEventHandler} from "../kernel/filesystem";
 export type {
-    IPCMessage,
-    IPCChannelListener,
-    IPCServiceOnConnectionCallback,
     UserspaceProcessManager,
-    UserspaceIPCManager,
     UserspaceProcessContext,
     UserspaceOtherProcessContext,
+    ProcessAttachment,
+    UserspaceIPCManager,
+    IPCMessage,
+    IPCChannelListener,
+    IPCServiceOnConnectionCallback,
 } from "../kernel/processes";
 export type {UserspaceWindowManager, UserspaceWindow, UserspaceOtherWindow, WindowEvent} from "../kernel/windowing";
-export type {UserspaceProgramRegistry} from "../kernel/prog_registry";
+export type {UserspaceProgramRegistry, ProgramRegistrant} from "../kernel/prog_registry";
 export type {SoundRegistry} from "../kernel/sfx_registry";
 
-export type {WrappedTerminal, ReadLineBuffer, ReadLineKeyHandler} from "../kernel/term_ctl";
+export type {WrappedTerminal, KeyEvent, KeyEventHandler, RegisteredKeyEventIdentifier, ReadLineBuffer, ReadLineKeyHandler} from "../kernel/term_ctl";
 
 export type {AbstractShell, AbstractShellMemory} from "../abstract_shell";

src/kernel/processes.ts

@@ -283,7 +283,7 @@ export class IPCManager {
 
 // TODO: could migrate the stuff where programs grab "scary" stuff like WindowManager and ProcessManager to be services
 
-enum ProcessAttachment {
+export enum ProcessAttachment {
     FOREGROUND,
     BACKGROUND,
     DETACHED,

src/kernel/prog_registry.ts

@@ -1,12 +1,17 @@
-import type { Program, ProgramRegistrant } from "../types";
-import type { AbstractFileSystem } from "./filesystem";
-import { ANSI, WrappedTerminal } from "./term_ctl";
+import type {Program} from "../types";
+import type {AbstractFileSystem} from "./filesystem";
+import {ANSI, WrappedTerminal} from "./term_ctl";
 
 const encode_js_to_url = (js_code: string): string => {
     const encoded = encodeURIComponent(js_code);
     return `data:text/javascript;charset=utf-8,${encoded}`;
 }
 
+export interface ProgramRegistrant {
+    program: Program<unknown>,
+    built_in: boolean,
+}
+
 export const build_registrant_from_js = async (js_code: string, built_in = false): Promise<ProgramRegistrant> => {
     // inspect the js code to see if it starts with "import". if so, this is outdated, put a deprecation warning
     let warn_deprecation = false;

src/kernel/term_ctl.ts

@@ -1,5 +1,4 @@
 import {IDisposable, ITerminalOptions, Terminal} from "@xterm/xterm";
-import type {KeyEvent, KeyEventHandler, RegisteredKeyEventIdentifier} from "../types";
 
 export const NEWLINE = "\r\n";
 /* eslint-disable-next-line no-control-regex, no-misleading-character-class */
@@ -82,6 +81,18 @@ export const ANSI = {
 
 // TODO: docstrings everywhere
 
+export interface KeyEvent {
+    key: string;
+    domEvent: KeyboardEvent;
+}
+
+export type KeyEventHandler = (event: KeyEvent, term: WrappedTerminal) => void | Promise<void>;
+
+export interface RegisteredKeyEventIdentifier {
+    key?: string;
+    domEventCode?: string;
+}
+
 export interface ReadLineBuffer {
     current_line: string;
     current_index: number;

src/types.ts

@@ -69,8 +69,6 @@ export interface Program<K = UserspaceKernel> {
 
 export type PrivilegedProgram = Program<Kernel>;
 
-// TODO: move some of these to their correct modules
-
 export interface CompletionData {
     term: WrappedTerminal,
     kernel: UserspaceKernel,
@@ -85,19 +83,3 @@ export interface CompletionData {
 
 // return null to fall back to default completion behavior (file paths)
 export type CompletionGenerator = (data: CompletionData) => Promise<string[] | null> | AsyncGenerator<string>;
-
-export interface ProgramRegistrant {
-    program: Program<unknown>,
-    built_in: boolean,
-}
-
-export interface KeyEvent {
-    key: string;
-    domEvent: KeyboardEvent;
-}
-
-export type KeyEventHandler = (event: KeyEvent, term: WrappedTerminal) => void | Promise<void>;
-export interface RegisteredKeyEventIdentifier {
-    key?: string;
-    domEventCode?: string;
-}

typedoc.json

@@ -1,4 +1,6 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["src/api_docs/index.ts"]
+  "entryPoints": ["src/api_docs/index.ts"],
+  "sort": ["required-first"],
+  "readme": "src/api_docs/README.md",
 }