more API docs

src/entities/note.js

@@ -93,13 +93,13 @@ class Note extends Entity {
     }
 
     /**
-     * @returns {Promise<Array.<Attribute>>} attributes belonging to this specific note (excludes inherited attributes)
+     * @returns {Promise<Attribute[]>} attributes belonging to this specific note (excludes inherited attributes)
      */
     async getOwnedAttributes() {
         return await repository.getEntities(`SELECT * FROM attributes WHERE isDeleted = 0 AND noteId = ?`, [this.noteId]);
     }
 
-    /** @returns {Promise<Array.<Attribute>>} all note's attributes, including inherited ones */
+    /** @returns {Promise<Attribute[]>} all note's attributes, including inherited ones */
     async getAttributes() {
         if (!this.__attributeCache) {
             await this.loadAttributesToCache();
@@ -108,12 +108,12 @@ class Note extends Entity {
         return this.__attributeCache;
     }
 
-    /** @returns {Promise<Array.<Attribute>>} all note's labels (attributes with type label), including inherited ones */
+    /** @returns {Promise<Attribute[]>} all note's labels (attributes with type label), including inherited ones */
     async getLabels() {
         return (await this.getAttributes()).filter(attr => attr.type === LABEL);
     }
 
-    /** @returns {Promise<Array.<Attribute>>} all note's relations (attributes with type relation), including inherited ones */
+    /** @returns {Promise<Attribute[]>} all note's relations (attributes with type relation), including inherited ones */
     async getRelations() {
         return (await this.getAttributes()).filter(attr => attr.type === RELATION);
     }
@@ -394,7 +394,7 @@ class Note extends Entity {
      * @param {string} type - attribute type (label, relation, etc.)
      * @param {string} name - attribute name
      * @param {string} [value] - attribute value
-     * @returns {Promise<Array.<Note>>}
+     * @returns {Promise<Note[]>}
      */
     async findNotesWithAttribute(type, name, value) {
         const params = [this.noteId, name];
@@ -432,7 +432,7 @@ class Note extends Entity {
      *
      * @param {string} name - label name
      * @param {string} [value] - label value
-     * @returns {Promise<Array.<Note>>}
+     * @returns {Promise<Note[]>}
      */
     async findNotesWithLabel(name, value) { return await this.findNotesWithAttribute(LABEL, name, value); }
 
@@ -441,35 +441,35 @@ class Note extends Entity {
      *
      * @param {string} name - relation name
      * @param {string} [value] - relation value
-     * @returns {Promise<Array.<Note>>}
+     * @returns {Promise<Note[]>}
      */
     async findNotesWithRelation(name, value) { return await this.findNotesWithAttribute(RELATION, name, value); }
 
     /**
      * Returns note revisions of this note.
      *
-     * @returns {Promise<Array.<NoteRevision>>}
+     * @returns {Promise<NoteRevision[]>}
      */
     async getRevisions() {
         return await repository.getEntities("SELECT * FROM note_revisions WHERE noteId = ?", [this.noteId]);
     }
 
     /**
-     * @returns {Promise<Array.<NoteImage>>}
+     * @returns {Promise<NoteImage[]>}
      */
     async getNoteImages() {
         return await repository.getEntities("SELECT * FROM note_images WHERE noteId = ? AND isDeleted = 0", [this.noteId]);
     }
 
     /**
-     * @returns {Promise<Array.<Branch>>}
+     * @returns {Promise<Branch[]>}
      */
     async getBranches() {
         return await repository.getEntities("SELECT * FROM branches WHERE isDeleted = 0 AND noteId = ?", [this.noteId]);
     }
 
     /**
-     * @returns {Promise<Array.<Note>>} child notes of this note
+     * @returns {Promise<Note[]>} child notes of this note
      */
     async getChildNotes() {
         return await repository.getEntities(`
@@ -483,7 +483,7 @@ class Note extends Entity {
     }
 
     /**
-     * @returns {Promise<Array.<Branch>>} child branches of this note
+     * @returns {Promise<Branch[]>} child branches of this note
      */
     async getChildBranches() {
         return await repository.getEntities(`
@@ -495,7 +495,7 @@ class Note extends Entity {
     }
 
     /**
-     * @returns {Promise<Array.<Note>>} parent notes of this note (note can have multiple parents because of cloning)
+     * @returns {Promise<Note[]>} parent notes of this note (note can have multiple parents because of cloning)
      */
     async getParentNotes() {
         return await repository.getEntities(`

src/public/javascripts/entities/note_short.js

@@ -25,7 +25,7 @@ class NoteShort {
         return this.mime === "application/json";
     }
 
-    /** @returns {Promise<Array.<Branch>>} */
+    /** @returns {Promise<Branch[]>} */
     async getBranches() {
         const branchIds = this.treeCache.parents[this.noteId].map(
             parentNoteId => this.treeCache.getBranchIdByChildParent(this.noteId, parentNoteId));
@@ -39,7 +39,7 @@ class NoteShort {
             && this.treeCache.children[this.noteId].length > 0;
     }
 
-    /** @returns {Promise<Array.<Branch>>} */
+    /** @returns {Promise<Branch[]>} */
     async getChildBranches() {
         if (!this.treeCache.children[this.noteId]) {
             return [];
@@ -51,22 +51,22 @@ class NoteShort {
         return await this.treeCache.getBranches(branchIds);
     }
 
-    /** @returns {Array.<string>} */
+    /** @returns {string[]} */
     getParentNoteIds() {
         return this.treeCache.parents[this.noteId] || [];
     }
 
-    /** @returns {Promise<Array.<NoteShort>>} */
+    /** @returns {Promise<NoteShort[]>} */
     async getParentNotes() {
         return await this.treeCache.getNotes(this.getParentNoteIds());
     }
 
-    /** @returns {Array.<string>} */
+    /** @returns {string[]} */
     getChildNoteIds() {
         return this.treeCache.children[this.noteId] || [];
     }
 
-    /** @returns {Promise<Array.<NoteShort>>} */
+    /** @returns {Promise<NoteShort[]>} */
     async getChildNotes() {
         return await this.treeCache.getNotes(this.getChildNoteIds());
     }

src/public/javascripts/services/frontend_script_api.js

@@ -6,6 +6,8 @@ import linkService from './link.js';
 import treeCache from './tree_cache.js';
 
 /**
+ * This is the main frontend API interface for scripts. It's published in the local "api" object.
+ *
  * @constructor
  * @hideconstructor
  */
@@ -40,10 +42,18 @@ function FrontendScriptApi(startNote, currentNote, originEntity = null) {
         await treeService.activateNote(notePath, true);
     };
 
+    /**
+     * @typedef {Object} ToolbarButtonOptions
+     * @property {string} title
+     * @property {string} [icon] - name of the jQuery UI icon to be used (e.g. "clock" for "ui-icon-clock" icon)
+     * @property {function} action - callback handling the click on the button
+     * @property {string} [shortcut] - keyboard shortcut for the button, e.g. "alt+t"
+     */
+
     /**
      * Adds new button the the plugin area.
      *
-     * @param {object} options
+     * @param {ToolbarButtonOptions} opts
      */
     this.addButtonToToolbar = opts => {
         const buttonId = "toolbar-button-" + opts.title.replace(/[^a-zA-Z0-9]/g, "-");
@@ -90,7 +100,7 @@ function FrontendScriptApi(startNote, currentNote, originEntity = null) {
      * Internally this serializes the anonymous function into string and sends it to backend via AJAX.
      *
      * @param {string} script - script to be executed on the backend
-     * @param {Array.<*>} params - list of parameters to the anonymous function to be send to backend
+     * @param {Array.<?>} params - list of parameters to the anonymous function to be send to backend
      * @return {Promise<*>} return value of the executed function on the backend
      */
     this.runOnServer = async (script, params = []) => {
@@ -121,9 +131,9 @@ function FrontendScriptApi(startNote, currentNote, originEntity = null) {
      * This is often used to bulk-fill the cache with notes which would have to be picked one by one
      * otherwise (by e.g. createNoteLink())
      *
-     * @param {Array.<string>} noteIds
+     * @param {string[]} noteIds
      * @param {boolean} [silentNotFoundError] - don't report error if the note is not found
-     * @return {Promise<Array.<NoteShort>>}
+     * @return {Promise<NoteShort[]>}
      */
     this.getNotes = async (noteIds, silentNotFoundError = false) => await treeCache.getNotes(noteIds, silentNotFoundError);
 

src/services/backend_script_api.js

@@ -13,6 +13,8 @@ const cloningService = require('./cloning');
 const messagingService = require('./messaging');
 
 /**
+ * This is the main backend API interface for scripts. It's published in the local "api" object.
+ *
  * @constructor
  * @hideconstructor
  */
@@ -73,7 +75,7 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
      *
      * @method
      * @param {string} SQL query
-     * @param {Array.<*>} array of params
+     * @param {Array.<?>} array of params
      * @returns {Promise<Entity|null>}
      */
     this.getEntity = repository.getEntity;
@@ -81,8 +83,8 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
     /**
      * @method
      * @param {string} SQL query
-     * @param {Array.<*>} array of params
+     * @param {Array.<?>} array of params
-     * @returns {Promise<Array.<Entity>>}
+     * @returns {Promise<Entity[]>}
      */
     this.getEntities = repository.getEntities;
 
@@ -92,7 +94,7 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
      * @method
      * @param {string} name - attribute name
      * @param {string} [value] - attribute value
-     * @returns {Promise<Array.<Note>>}
+     * @returns {Promise<Note[]>}
      */
     this.getNotesWithLabel = attributeService.getNotesWithLabel;
 
@@ -139,14 +141,30 @@ function BackendScriptApi(startNote, currentNote, originEntity) {
      */
     this.toggleNoteInParent = cloningService.toggleNoteInParent;
 
+    /**
+     * @typedef {object} CreateNoteAttribute
+     * @property {string} type - attribute type - label, relation etc.
+     * @property {string} name - attribute name
+     * @property {string} [value] - attribute value
+     */
+
+    /**
+     * @typedef {object} CreateNoteExtraOptions
+     * @property {boolean} [json=false] - should the note be JSON
+     * @property {boolean} [isProtected=false] - should the note be protected
+     * @property {string} [type='text'] - note type
+     * @property {string} [mime='text/html'] - MIME type of the note
+     * @property {CreateNoteAttribute[]} [attributes=[]] - attributes to be created for this note
+     */
+
     /**
      * @method
      *
      * @param {string} parentNoteId - create new note under this parent
      * @param {string} title
-     * @param {string} [content]
+     * @param {string} [content=""]
-     * @param {object} [extraOptions]
+     * @param {CreateNoteExtraOptions} [extraOptions={}]
-     * @returns {Promise<Object>} object contains attributes "note" and "branch" which contain newly created entities
+     * @returns {Promise<{note: Note, branch: Branch}>} object contains newly created entities note and branch
      */
     this.createNote = noteService.createNote;