From 57e68857a69e20adffb6e35e13754358eb1e31ea Mon Sep 17 00:00:00 2001
From: jsteuer <jan.niklas.steuer@gmail.com>
Date: Fri, 05 Jul 2019 12:39:43 +0200
Subject: [PATCH] better api docs
---
mathcoach-api.d.ts | 86 ++++++++++++++++++++++++++++++++++++++++---
1 files changed, 80 insertions(+), 6 deletions(-)
diff --git a/mathcoach-api.d.ts b/mathcoach-api.d.ts
index d4ab7a2..b5ed739 100644
--- a/mathcoach-api.d.ts
+++ b/mathcoach-api.d.ts
@@ -20,9 +20,33 @@
*/
interface Api {
/**
- * Die Schnittstelle zur Entwicklungsumgebung (IDE) von MathCoach
+ * Die Schnittstelle zur Entwicklungsumgebung (IDE) von MathCoach.
*/
readonly ide: IdeApi;
+
+ /**
+ * Prüft, ob die API einsatzbereit ist. Dies sollte einmalig, beim Start des Werkzeugs,
+ * geprüft werden. Dabei bedeutet der Rückgabewert `true`, dass das Werkzeug durch
+ * die IDE gestartet wurde und die Kommunikation möglich ist. `false` bedeutet, dass
+ * das Werkzeug nicht durch die IDE gestartet wurde.
+ *
+ * Somit wäre es möglich ein Tool offlinefähig zu machen, indem es ggf. eine eigene
+ * Implementierung der MathCoach-API (beispielsweise unter Verwendung des LocalStorage
+ * zum Speichern von Dateien) verwendet.
+ *
+ * Anwendungsbeispiel (Prüft zusätzlich, ob die globale `MC`-Variable verfügbar ist - also
+ * die `ide-lib.js` korrekt eingebunden und geladen wurde):
+ *
+ * let isReady = (typeof MC !== "undefined") ? await MC.isReady() : false;
+ * if(isReady){
+ * // MathCoach-API is ready to use!
+ * }else{
+ * // MathCoach-API is not ready...
+ * }
+ *
+ *
+ */
+ isReady(): Promise<boolean>;
}
@@ -31,11 +55,21 @@
*/
interface IdeApi {
/**
- * Name des aktuellen Benutzers
+ * Name des aktuellen Benutzers.
+ *
+ * Anwendungsbeisipiel:
+ *
+ * let user = await MC.ide.getUserName();
+ *
*/
getUserName(): Promise<string>;
/**
- * Verweis auf die Datei, mit dem das Entwicklerwerkzeug gestartet wurde.
+ * Verweis auf die Datei, mit der das Entwicklerwerkzeug gestartet wurde.
+ *
+ * Anwendungsbeispiel:
+ *
+ * let file = await MC.ide.getContextFile();
+ * let { owner, path, part } = file;
*/
getContextFile(): Promise<File>;
/**
@@ -43,7 +77,7 @@
*/
readonly fs: FileSystemApi;
/**
- * Schnittstelle zur Navigations-Vorschau
+ * Schnittstelle zur Vorschau
*/
readonly navigator: NavigatorApi;
}
@@ -53,17 +87,43 @@
interface NavigatorApi {
/**
* Navigiert die Vorschau zu einem Link.
+ *
+ * Anwendungsbeispiel:
+ *
+ * await MC.ide.navigator.navigateTo("/mathcoach/www/yourName/readme.html", true)
+ *
+ *
* @param link Web URL (z.B. zu einer Datei im WWW-Verzeichnis oder einer MathCoach-Aufgabe)
* @param forceOpen `true` um das Anzeigen der Vorschau zu erzwingen, `false` um nur bei bereits geöffneter Vorschau zu navigieren.
*/
navigateTo(link: string, forceOpen?: boolean): Promise<void>;
+
+ /**
+ * Navigiert die Vorschau zu einer MathCoach-Aufgabe.
+ * Hinweis: Die Datei muss im `vfs`-Teil des Dateisystems liegen und
+ * eine ausführbar sein (z.B. eine groovy-Datei).
+ *
+ * Anwendungsbeispiel:
+ *
+ * let file = { part: "vfs", owner:"yourName", path: "/myExercise.groovy" }
+ * await MC.ide.navigator.navigateToExercise(file)
+ *
+ * @param file Datei-Verweis
+ */
+ navigateToExercise(file: MathCoach.File, forceOpen?: boolean): Promise<void>
}
/**
* Schnittstelle zum Dateisystem
*/
interface FileSystemApi {
/**
- * Liest eine Datei
+ * Liest eine Datei und gibt den Textinhalt zurück.
+ *
+ * Anwendungsbeispiel: Lesen der Datei, mit dem das Werkzeug gestartet wurde
+ *
+ * let file = await MC.ide.getContextFile();
+ * let text = await MC.ide.fs.readFile(file);
+ * // do something with the text, e.g. JSON.parse(text)
*
* @param file Verweis auf die Datei
*/
@@ -71,13 +131,27 @@
/**
* Schreibt Text in eine Datei.
*
+ * Anwendungsbeispiel: Schreiben der Datei, mit dem das Werkzeug gestartet wurde
+ *
+ * let file = await MC.ide.getContextFile(); // some file reference
+ * let text = "some text"; // or JSON.stringify(yourDataContainer)
+ * await MC.ide.fs.writeFile(file,text);
+ *
* @param file Verweis auf die Datei
* @param text Der neue Inhalt der Datei
*/
writeFile(file: File, text: string): Promise<void>;
}
/**
- * Eindeutiger Verweis auf eine Datei
+ * Eindeutiger Verweis auf eine Datei.
+ *
+ * Anwendungsbeispiel:
+ *
+ * let user = await MC.ide.getUserName(); // oder von einem anderen File-Objekt abgfragen...
+ * let file = { owner: user, part: "vfs", path:"/myExercise.groovy" }
+ *
+ * Siehe auch: `MC.ide.getContextFile()`
+ *
*/
interface File {
/**
--
Gitblit v1.10.0-SNAPSHOT