📝 Include everything in docs

fushra · Jul 29, 2021 · 578ec6c · 578ec6c
1 parent 8eff61d
commit 578ec6c
Show file tree

Hide file tree

Showing 12 changed files with 88 additions and 20 deletions.
diff --git a/examples/css.html b/examples/css.html
@@ -1 +1 @@
-<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p><link rel="stylesheet" type="type/css" rel="assets/1.css"></body></html>
+<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p></body></html>
diff --git a/examples/helloWorld.html b/examples/helloWorld.html
@@ -1,3 +1 @@
-<!DOCTYPE html><html><head><title>Hello World!</title></head><body><!-- Start of meml component: navBar --><div>hello world from the nav</div><!-- End of meml component: navBar --><p>Basic website made with MEML!</p><p>1 + 2 = 3</p><p>BODMAS: -15</p><p>Brackets: 21</p><p>This string contains \"Excaped characters\"</p><!-- Start of meml component: helloComponent --><p>Hello TrickyPR. This comes from a component!</p><p>Test</p><!-- End of meml component: helloComponent --><a href="https://fushra.com" >Our website!</a><!-- This code was embedded from a HTML file -->
-<p>Hello from an imported html file!</p>
-<!-- Start of meml component: logic --><p>Hello TrickyPR</p><!-- End of meml component: logic --><!-- Start of meml component: logic --><p>Hello _trickypr</p><!-- End of meml component: logic --><!-- Start of meml component: logic --><p>Who are you?!</p><!-- End of meml component: logic --><p>Count: 0</p><p>Count: 1</p><p>Count: 2</p><p>Count: 3</p><p>Count: 4</p><p>Count: 5</p>fine</body></html>
+<!DOCTYPE html><html><head><title>Hello World!</title></head><body><!-- Start of meml component: navBar --><div>hello world from the nav</div><!-- End of meml component: navBar --><p>Basic website made with MEML!</p><p>1 + 2 = 3</p><p>BODMAS: -15</p><p>Brackets: 21</p><p>This string contains \"Excaped characters\"</p><!-- Start of meml component: helloComponent --><p>Hello TrickyPR. This comes from a component!</p><p>Test</p><!-- End of meml component: helloComponent --><a href="https://fushra.com" >Our website!</a><!-- Start of meml component: logic --><p>Hello TrickyPR</p><!-- End of meml component: logic --><!-- Start of meml component: logic --><p>Hello _trickypr</p><!-- End of meml component: logic --><!-- Start of meml component: logic --><p>Who are you?!</p><!-- End of meml component: logic --><p>Count: 0</p><p>Count: 1</p><p>Count: 2</p><p>Count: 3</p><p>Count: 4</p><p>Count: 5</p>fine</body></html>
diff --git a/examples/newFolder/css.html b/examples/newFolder/css.html
@@ -1 +1 @@
-<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p><link rel="stylesheet" type="type/css" rel="../assets/1.css"></body></html>
+<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p></body></html>
diff --git a/package.json b/package.json
@@ -27,7 +27,7 @@
     "ast": "ts-node ./scripts/GenerateAst.ts && prettier . --write",
     "app": "ts-node ./src/app.ts",
     "build": "tsc && echo '#!/usr/bin/env node\n' >  tmpfile && cat ./dist/app.js >> tmpfile && mv tmpfile ./dist/app.js",
-    "build:docs": "typedoc --tsconfig tsconfig.json",
+    "docs": "typedoc --tsconfig tsconfig.json",
     "examples": "yarn app --file ./css.meml --file ./helloWorld.meml --file newFolder/css.meml --src ./examples --out ./examples",
     "prepublishOnly": "yarn build",
     "quality": "jscpd src/"

diff --git a/src/core.ts b/src/core.ts
@@ -64,11 +64,11 @@ import {
  *
  * # Project management
  *
- * TODO: Should config be moved somewhere else?
+ * @TODO Should config be moved somewhere else?
  *
- * TODO: Should builds be moved into separate functions?
+ * @TODO Should builds be moved into separate functions?
  *
- * TODO: Move error reporting out of this class.
+ * @TODO Move error reporting out of this class.
  */
 export class MemlCore {
   /**
@@ -150,16 +150,24 @@ export class MemlCore {
    * for parsing
    */
   tokenize(source: string, file = ''): Token[] {
-    const scanner = new Scanner(source, file)
-    return scanner.scanTokens()
+    try {
+      const scanner = new Scanner(source, file)
+      return scanner.scanTokens()
+    } catch (e) {
+      throw new Error(`${e.message}\n    MemlCore.tokenize`)
+    }
   }
 
   /**
    * Converts the input tokens to an AST tree with a PageStmt as its root
    */
   parse(tokens: Token[], file = ''): PageStmt {
-    const parser = new Parser(tokens, file)
-    return parser.parse()
+    try {
+      const parser = new Parser(tokens, file)
+      return parser.parse()
+    } catch (e) {
+      throw new Error(`${e.message}\n    MemlCore.parse`)
+    }
   }
 
   /**
@@ -168,8 +176,12 @@ export class MemlCore {
    * May write files to disk depending on your settings for `shouldLink`
    */
   targetWeb(page: PageStmt, path = 'memory.meml'): Promise<string> {
-    const target = new Web(path)
-    return target.convert(page)
+    try {
+      const target = new Web(path)
+      return target.convert(page)
+    } catch (e) {
+      throw new Error(`${e.message}\n    MemlCore.targetWeb`)
+    }
   }
 
   tokenizeAndParse(source: string, file = ''): PageStmt {
@@ -199,6 +211,11 @@ export class MemlCore {
     return this.sourceToWeb((await readFile(path)).toString(), path)
   }
 
+  /**
+   * Resets all errors generated by the compiler and linker cache. **Do not use**
+   * between files, only between compilations. Use `MemlCore.resetErrors()`
+   * between files.
+   */
   static reset(): void {
     this.resetErrors()
     resetLinker()
@@ -207,11 +224,18 @@ export class MemlCore {
   // ------------------------------------------------------------
   // Error functions
 
+  /**
+   * Resets `MemlCore.hadError` and `MemlCore.errors`
+   */
   static resetErrors(): void {
     this.hadError = false
     this.errors = ''
   }
 
+  /**
+   * Internal error reporting function for reporting an error at a specific
+   * token
+   */
   static errorAtToken(token: Token, message: string, file = ''): void {
     if (token.type === TokenType.EOF) {
       this.report(token.line, ' at end', message, '', file)
@@ -226,10 +250,17 @@ export class MemlCore {
     }
   }
 
+  /**
+   * Internal error reporting function
+   */
   static error(line: number, message: string, file = ''): void {
     this.report(line, '', message, file)
   }
 
+  /**
+   * Internal error reporting function for reporting an linter warning at a specific
+   * token
+   */
   static linterAtToken(token: Token, message: string): void {
     this.warn(
       token.line,
@@ -240,10 +271,16 @@ export class MemlCore {
     )
   }
 
+  /**
+   * Internal warning function
+   */
   static generalWarning(line: number, message: string): void {
     this.warn(line, 'General', '', message)
   }
 
+  /**
+   * Private error reporting function
+   */
   private static report(
     line: number,
     where: string,
@@ -264,6 +301,9 @@ export class MemlCore {
     }] Error${where}: ${message}\n${this.formatContext(context)}\n`
   }
 
+  /**
+   * Private warning function
+   */
   private static warn(
     line: number,
     type: 'Linter' | 'General',
@@ -284,10 +324,16 @@ export class MemlCore {
     )}\n`
   }
 
+  /**
+   * Internal error formatting function
+   */
   static formatContext(context: string): string {
     return `    ┃${context.replace(/\n/g, '\n    ┃')}`
   }
 
+  /**
+   * Register a new loader for linking and rendering
+   */
   static registerLoader(Loader: ILoader): void {
     this.globalLoaders.push(Loader)
   }

diff --git a/src/parser/AstNodes.ts b/src/parser/AstNodes.ts
@@ -0,0 +1,2 @@
+export * from './Expr'
+export * from './Stmt'
diff --git a/src/parser/index.ts b/src/parser/index.ts
@@ -1 +1,2 @@
+export * as AstNodes from './AstNodes'
 export * from './Parser'
diff --git a/src/targets/Targets.ts b/src/targets/Targets.ts
@@ -0,0 +1,2 @@
+export * from './Web'
+export * from './shared'
diff --git a/src/targets/imports.ts b/src/targets/imports.ts
@@ -2,8 +2,9 @@ import { readFile } from 'fs/promises'
 import { dirname, join } from 'path'
 import fetch from 'node-fetch'
 
-import { MemlCore, relativeLink } from '../index'
+import { MemlCore } from '../index'
 import { ImportStmt } from '../parser/Stmt'
+import { relativeLink } from './loaders'
 
 export async function contentImport({
   isUrl,

diff --git a/src/targets/index.ts b/src/targets/index.ts
@@ -1,3 +1,17 @@
-export * from './Web'
-export * from './loaders'
-export * from './shared'
+export * as Targets from './Targets'
+
+/**
+ * Loaders are the method of resolving and loading files into the MEML web targeter.
+ * The easiest way to add a new language to the web target, is to add a custom
+ * loader. All loaders must implement {@Link ILoader} and all necessary
+ * methods.
+ *
+ *
+ *
+ * Additionally, if you want to use a custom loader system (e.g. webpack), you
+ * would implement ILoader, wipe {@Link MemlCore.globalLoaders} and add your
+ * own loader
+ *
+ * @TODO Migrate linker.ts to a class that can be extended and overridden for additional support of other builders (e.g. webpack)
+ */
+export * as Loaders from './loaders'
diff --git a/src/targets/shared/TargetBase.ts b/src/targets/shared/TargetBase.ts
@@ -2,6 +2,10 @@ import { BinaryExpr } from '../../parser/Expr'
 import { TokenType } from '../../scanner/TokenTypes'
 import { Environment, EnvStore, EnvValidTypes } from './Environment'
 
+/**
+ * This is an internal class for creating a new target. You can extend it to create
+ * a new target. Expected to implement ExprVisitor and StmtVisitor. See `Web`
+ */
 export class TargetBase {
   environment = new Environment()
   exports = new Map<string, EnvStore>()

diff --git a/tsconfig.json b/tsconfig.json
@@ -18,7 +18,7 @@
   },
   "include": ["src/**/*"],
   "typedocOptions": {
-    "entryPoints": ["src/core.ts"],
+    "entryPoints": ["src/index.ts"],
     "out": "docs-dist"
   }
 }
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p><link rel="stylesheet" type="type/css" rel="assets/1.css"></body></html>
		<!DOCTYPE html><html><head><title>CSS example</title></head><body><h1>Roses are red</h1><h2>Violets are blue</h2><span>Poems are hard</span><p>I am sorry</p></body></html>
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		export * as AstNodes from './AstNodes'
		export * from './Parser'
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		export * from './Web'
		export * from './shared'