Open Source Dokumentenmanagement
Dokumentation

Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core JavaScript-API

Monaco-Editor und JSDoc

Der Monaco-Editor ist integraler Bestandteil von agorum core und bietet Entwicklern eine leistungsfähige Umgebung zur Bearbeitung und Verwaltung des JavaScript-Codes für Eigenentwicklungen und Anpassungen der Standardfunktionalität. Einige Funktionen des Monaco-Editors sind: 

JSDoc ist ein Dokumentationswerkzeug, das speziell für JavaScript entwickelt wurde, um den Code mit Kommentaren zu versehen, die sowohl für Entwickler als auch für automatische Dokumentationstools nützlich sind. Es hilft, den Code besser lesbar und verständlicher zu machen, indem es ermöglicht, Funktionen, Parameter, Rückgabewerte und andere Elemente des Codes detailliert zu beschreiben. Der Monaco-Editor unterstützt JSDoc und kann daher auch Unterstützung für die agorum-Funktionen sowie Ihre eigenen Code-Erweiterungen anbieten.

Anzeige von Code-Kommentaren im Editor

 

Hinweis: Beachten Sie, dass Sie JSDoc nur im Monaco-Editor verwenden können und nicht in den älteren Entwicklungsoberflächen, etwa Support Tool oder smart assistant konfigurator. In den älteren Entwicklungsoberflächen wird der Editor CodeMirror verwendet.

Wenn Sie agorum core um Funktionalität erweitern, die Sie auch anderen Entwicklern zur Verfügung stellen wollen, ergänzen Sie daher JSDoc-Kommentare in Ihrem Code. Allgemeine Hinweise zu JSDoc finden Sie unter jsdoc.app.

In den folgenden Abschnitten finden Sie einige grundlegende Hinweise zum Monaco-Editor und zur Verwendung von JSDoc.

Kurzüberblick über den Monaco-Editor

Der Monaco-Editor bietet einige Funktionen, die bei der Entwicklung sehr hilfreich sein können. Diese werden im Folgenden kurz erläutert.

 

Kontextmenü im Monaco-Editor

Klicken Sie etwa auf den Namen einer Funktion oder Variablen, öffnen sich über ein Kontextmenü diverse Aktionen.

Aktion Beschreibung Tastaturkürzel
Go to Definition Springt zur Stelle im Code, in der die Funktion oder Variable definiert ist. STRG + F12
STRG + Linksklick
Go to References Listet alle vorhandenen Stellen im Code auf, in denen die Funktion oder Variable verwendet wird, und springt an die entsprechende Stelle. SHIFT + F12
Go to Symbol Listet alle verfügbaren Variablen, Funktionen und sonstigen Symbole im Code auf und springt an die entsprechende Stelle. STRG + SHIFT + O
Peek > Peek Definition Zeigt die Stelle, in der die Variable oder Funktion definiert wurde, in einer Vorschau an.

Diese Aktion zeigt auch externe Dateien an, d. h. die Definition muss nicht in der gleichen Datei durchgeführt worden sein, in der die Variable oder Funktion verwendet wird.		 ALT + F12
Peek > Peek References Zeigt die Stellen, in der die Variable oder Funktion verwendet wird, in einer Vorschau an.

Diese Aktion zeigt auch externe Dateien an, d. h. Dateien, in denen die Variable oder Funktion ebenfalls verwendet wird.		  
Rename Symbol Benennt alle Stellen, in denen die Funktion oder die Variable im Code vorkommt, gleichzeitig um. F2
Change All Occurrences Ermöglicht es, alle Stellen, in denen die Funktion oder die Variable im Code vorkommt, gleichzeitig zu ändern. STRG + F2
Format Document Formatiert den gesamten Code automatisch einheitlich. SHIFT + ALT + F
Format Selection Formatiert den Code-Abschnitt, in dem Sie sich gerade befinden, automatisch einheitlich. STRG + K STRG + F
Cut Schneidet markierten Code aus.  
Copy Kopiert markierten Code.  
Command Palette Öffnet eine integrierte Hilfe. F1

Außerdem können Sie folgende Tastaturkürzel verwenden:

Tastaturkürzel Beschreibung
STRG + ALT + Pfeiltaste hoch/runter Lässt einen weiteren Cursor ober- oder unterhalb der aktuellen Zeile erscheinen.

Wenn Sie nach dem Erscheinen des Cursors tippen, können Sie in mehrere Zeilen schreiben, um etwa in mehreren Zeilen die Formatierung zu ändern, wenn Copy-and-paste nicht funktioniert, weil etwa Variablen anders lauten.
SHIFT + ALT + Pfeiltaste hoch/runter Kopiert eine oder mehrere Codezeilen.
ALT + Pfeiltaste hoch/runter Verschiebt eine oder mehrere Codezeilen.

Verwenden Sie das Verschieben, nachdem Sie Codezeilen mit SHIFT + ALT + Pfeiltaste hoch/runter kopiert haben, um Codezeilen zu duplizieren, an eine gewünschte Stelle zu verschieben und dann zu ändern.
STRG + G Öffnet eine Liste, in der Sie die Nummer einer Codezeile eingeben können, und springt zu der eingegebenen Zeile.
STRG + U Springt bei jedem Ausführen von STRG + U in die Cursorposition zurück, die zuvor aufgerufen wurde.

Grundlegende JSDoc-Syntax

JSDoc-Kommentare beginnen mit /** und enden mit */. Innerhalb dieser Kommentare werden verschiedene Tags verwendet, die mit einem @ beginnen, um die Struktur und Bedeutung des Codes zu beschreiben.

/**
 * Addiert zwei Zahlen.
 *
 * @param {number} a - Die erste Zahl.
 * @param {number} b - Die zweite Zahl.
 * @returns {number} Die Summe der beiden Zahlen.
 */
function add(a, b) {
    return a + b;
}

Wichtige JSDoc-Tags

Die folgenden Tags werden häufig in JSDoc-Kommentaren verwendet:

Tag Beschreibung
@param {Typ} Name Beschreibung Beschreibt die Parameter einer Funktion mit Typ, Name und einer optionalen Beschreibung. 
/**
 * Addiert zwei Zahlen.
 * 
 * @param {number} a - Die erste Zahl.
 * @param {number} b - Die zweite Zahl.
 * @return {number} Die Summe der beiden Zahlen.
 */
function add(a, b) {
    return a + b;
}

 

Anzeige der @param-Dokumentation
@return {Typ} Beschreibung Das @return-Tag (oder @returns) beschreibt den Rückgabewert einer Funktion.  
/**
 * Gibt einen Willkommensgruß zurück.
 *
 * @return {string} Eine Willkommensnachricht.
 */
function welcome() {
  return 'Willkommen!';
}

 

Anzeige der @return-Dokumentation
@typedef {Typ} Name und @property {Typ} Name Beschreibung Das @typedef-Tag wird verwendet, um benutzerdefinierte Typen zu definieren, die in der gesamten Dokumentation genutzt werden können. Das @property-Tag beschreibt die Eigenschaften eines Objekts. 
/**
 * Ein Auto.
 *
 * @typedef {Object} Car
 * @property {string} make - Der Hersteller des Autos.
 * @property {string} model - Das Modell des Autos.
 * @property {number} year - Das Baujahr des Autos.
 */

/**
 * Gibt eine Beschreibung eines Autos zurück.
 *
 * @param {Car} car - Das Auto, das beschrieben werden soll.
 * @return {string} Eine Beschreibung des Autos.
 */
function describeCar(car) {
  return 'Das Auto ist ein ' + car.year + ' ' + car.make + ' ' + car.model + '.';
}

 

Anzeige der @property-Dokumentation
@todo Beschreibung Das @todo-Tag wird verwendet, um ausstehende Arbeiten oder Ideen für zukünftige Implementierungen zu vermerken. 
/**
 * Berechnet den Umfang eines Rechtecks.
 *
 * @param {number} width - Die Breite des Rechtecks.
 * @param {number} height - Die Höhe des Rechtecks.
 * @return {number} Der Umfang des Rechtecks.
 * @todo Funktion auf andere Formen erweitern.
 */
function calculatePerimeter(width, height) {
  return 2 * (width + height);
}

 

Anzeige der @todo-Dokumentation
@throws {Error} Beschreibung Dokumentiert, welche Fehler eine Funktion werfen kann. 
/**
 * Teilt zwei Zahlen.
 *
 * @param {number} a - Der Dividend.
 * @param {number} b - Der Divisor.
 * @throws {Error} Wenn der Divisor null ist.
 * @return {number} Das Ergebnis der Division.
 */
function divide(a, b) {
  if (b === 0) {
    throw new Error('Division durch null ist nicht erlaubt.');
  }
  return a / b;
}

 

Anzeige der @throws-Dokumentation
@example Beschreibung Das @example-Tag bietet Beispielcode zur Veranschaulichung der Verwendung einer Funktion oder Methode. 
/**
 * Multipliziert zwei Zahlen.
 * 
 * @param {number} a - Der erste Faktor.
 * @param {number} b - Der zweite Faktor.
 * @return {number} Das Produkt der beiden Zahlen.
 * @example
 * var result = multiply(2, 3);
 * // Ergebnis: 6
 */
function multiply(a, b) {
    return a * b;
}

 

Anzeige der @example-Dokumentation
@deprecated Beschreibung und @see Beschreibung Das @deprecated-Tag zeigt an, dass eine Funktion oder Methode veraltet ist und in der Zukunft entfernt wird. Das @see-Tag wird verwendet, um auf andere relevante Ressourcen oder Dokumentationen zu verweisen. 
/**
 * Berechnet den Flächeninhalt eines Rechtecks.
 *
 * @deprecated Seit Version 2.0.0. Verwenden Sie stattdessen die Funktion `calculateArea`.
 * @param {number} width - Die Breite des Rechtecks.
 * @param {number} height - Die Höhe des Rechtecks.
 * @return {number} Der Flächeninhalt des Rechtecks.
 * @see calculateArea
 */
function getArea(width, height) {
  return width * height;
}

/**
 * Berechnet den Flächeninhalt einer Form mit der angegebenen Breite und Höhe.
 *
 * @param {number} width - Die Breite der Form.
 * @param {number} height - Die Höhe der Form.
 * @return {number} Der Flächeninhalt der Form.
 */
function calculateArea(width, height) {
  return width * height;
}

// Beispielhafte Nutzung
var area = calculateArea(5, 10);
console.log('Der Flächeninhalt ist:', area);
// Ausgabe: Der Flächeninhalt ist: 50

 

Anzeige der @deprecated-Dokumentation

Typ-Angaben in JSDoc

JSDoc unterstützt neben den Standard-Datentypen auch die agorum-spezifischen Datentypen. Im Folgenden finden Sie eine Übersicht über die wichtigsten Standard-Datentypen und agorum core-Typen.

  1. Primitive Datentypen:

    • @type {number}: Eine Zahl, entweder Ganzzahl oder Gleitkommazahl.
    • @type {string}: Eine Zeichenkette.
    • @type {boolean}: Ein Boolescher Wert (true oder false).
    • @type {null}: Der spezielle Typ null.
    • @type {undefined}: Wenn der Wert undefined ist.

  2. Objekte und Arrays:

    • @type {Object}: Ein allgemeines Objekt.
    • @type {Array<number>}: Ein Array von Zahlen.
    • @type {Array<string>}: Ein Array von Zeichenketten.

  3. Sonstige Typen:

    • @type {Function}: Eine Funktion.
    • @type {Array}: Ein allgemeines Array.
    • @type {?Type}: Ein Typ, der null oder des angegebenen Typs sein kann (Nullable Type).
    • @type {!Type}: Ein Typ, der nicht null sein darf (Non-nullable Type).

  4. agorum core-Typen:

    • @type {agorum.FileObject}: Ein Dokument-Objekt.
    • @type {agorum.FolderObject}: Ein Ordner-Objekt.
    • @type {agorum.MailObject}: Ein Mail-Objekt.
    • @type {agorum.Object}: Ein agorum-Objekt.
    • @type {agorum.SessionController}: Ein SessionController-Objekt.
    • @type {agorum.UserObject}: Ein Benutzer-Objekt.

Sie könen einen agorum core-Typ aus einer LIste aller verfügbaren Typen auswählen, indem Sie anstelle des Datentyps den Namespace agorum. eingeben und auf die Autovervollständigung warten.

 

Anzeige der agorum-Typen mit der Autovervollständigung