Skip to content

Commit

Permalink
Added jsdoc for the node part of etherpad. (#5983)
Browse files Browse the repository at this point in the history
  • Loading branch information
@SamTV12345
SamTV12345 authored Oct 17, 2023
1 parent 53d1e8a commit ff1b929
Show file tree
Hide file tree
Showing 16 changed files with 272 additions and 59 deletions.
73 changes: 65 additions & 8 deletions src/node/db/API.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const exportTxt = require('../utils/ExportTxt');
const importHtml = require('../utils/ImportHtml');
const cleanText = require('./Pad').cleanText;
const PadDiff = require('../utils/padDiff');
const { checkValidRev, isInt } = require('../utils/checkValidRev');
const {checkValidRev, isInt} = require('../utils/checkValidRev');

/* ********************
* GROUP FUNCTIONS ****
Expand Down Expand Up @@ -193,6 +193,13 @@ Example returns:
{code: 1, message:"padID does not exist", data: null}
{code: 1, message:"text too long", data: null}
*/
/**
*
* @param {String} padID the id of the pad
* @param {String} text the text of the pad
* @param {String} authorId the id of the author, defaulting to empty string
* @returns {Promise<void>}
*/
exports.setText = async (padID, text, authorId = '') => {
// text is required
if (typeof text !== 'string') {
Expand All @@ -214,7 +221,10 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
{code: 1, message:"text too long", data: null}
*/
@param {String} padID the id of the pad
@param {String} text the text of the pad
@param {String} authorId the id of the author, defaulting to empty string
*/
exports.appendText = async (padID, text, authorId = '') => {
// text is required
if (typeof text !== 'string') {
Expand All @@ -233,6 +243,9 @@ Example returns:
{code: 0, message:"ok", data: {text:"Welcome <strong>Text</strong>"}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {String} rev the revision number, defaulting to the latest revision
@return {Promise<{html: string}>} the html of the pad
*/
exports.getHTML = async (padID, rev) => {
if (rev !== undefined) {
Expand Down Expand Up @@ -265,6 +278,10 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {String} html the html of the pad
@param {String} authorId the id of the author, defaulting to empty string
*/
exports.setHTML = async (padID, html, authorId = '') => {
// html string is required
Expand Down Expand Up @@ -303,6 +320,9 @@ Example returns:
{code: 1, message:"start is higher or equal to the current chatHead", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {Number} start the start point of the chat-history
@param {Number} end the end point of the chat-history
*/
exports.getChatHistory = async (padID, start, end) => {
if (start && end) {
Expand Down Expand Up @@ -349,6 +369,10 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {String} text the text of the chat-message
@param {String} authorID the id of the author
@param {Number} time the timestamp of the chat-message
*/
exports.appendChatMessage = async (padID, text, authorID, time) => {
// text is required
Expand Down Expand Up @@ -378,6 +402,7 @@ Example returns:
{code: 0, message:"ok", data: {revisions: 56}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.getRevisionsCount = async (padID) => {
// get the pad
Expand All @@ -392,6 +417,7 @@ Example returns:
{code: 0, message:"ok", data: {savedRevisions: 42}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.getSavedRevisionsCount = async (padID) => {
// get the pad
Expand All @@ -406,6 +432,7 @@ Example returns:
{code: 0, message:"ok", data: {savedRevisions: [2, 42, 1337]}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.listSavedRevisions = async (padID) => {
// get the pad
Expand All @@ -420,6 +447,8 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {Number} rev the revision number, defaulting to the latest revision
*/
exports.saveRevision = async (padID, rev) => {
// check if rev is a number
Expand Down Expand Up @@ -451,6 +480,8 @@ Example returns:
{code: 0, message:"ok", data: {lastEdited: 1340815946602}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@return {Promise<{lastEdited: number}>} the timestamp of the last revision of the pad
*/
exports.getLastEdited = async (padID) => {
// get the pad
Expand All @@ -466,6 +497,9 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"pad does already exist", data: null}
@param {String} padName the name of the new pad
@param {String} text the initial text of the pad
@param {String} authorId the id of the author, defaulting to empty string
*/
exports.createPad = async (padID, text, authorId = '') => {
if (padID) {
Expand All @@ -491,6 +525,7 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.deletePad = async (padID) => {
const pad = await getPadSafe(padID, true);
Expand All @@ -504,6 +539,9 @@ exports.deletePad = async (padID) => {
{code:0, message:"ok", data:null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {Number} rev the revision number, defaulting to the latest revision
@param {String} authorId the id of the author, defaulting to empty string
*/
exports.restoreRevision = async (padID, rev, authorId = '') => {
// check if rev is a number
Expand Down Expand Up @@ -568,6 +606,9 @@ Example returns:
{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
@param {String} sourceID the id of the source pad
@param {String} destinationID the id of the destination pad
@param {Boolean} force whether to overwrite the destination pad if it exists
*/
exports.copyPad = async (sourceID, destinationID, force) => {
const pad = await getPadSafe(sourceID, true);
Expand All @@ -582,6 +623,10 @@ Example returns:
{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
@param {String} sourceID the id of the source pad
@param {String} destinationID the id of the destination pad
@param {Boolean} force whether to overwrite the destination pad if it exists
@param {String} authorId the id of the author, defaulting to empty string
*/
exports.copyPadWithoutHistory = async (sourceID, destinationID, force, authorId = '') => {
const pad = await getPadSafe(sourceID, true);
Expand All @@ -596,6 +641,9 @@ Example returns:
{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
@param {String} sourceID the id of the source pad
@param {String} destinationID the id of the destination pad
@param {Boolean} force whether to overwrite the destination pad if it exists
*/
exports.movePad = async (sourceID, destinationID, force) => {
const pad = await getPadSafe(sourceID, true);
Expand All @@ -610,6 +658,7 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.getReadOnlyID = async (padID) => {
// we don't need the pad object, but this function does all the security stuff for us
Expand All @@ -628,6 +677,7 @@ Example returns:
{code: 0, message:"ok", data: {padID: padID}}
{code: 1, message:"padID does not exist", data: null}
@param {String} roID the readonly id of the pad
*/
exports.getPadID = async (roID) => {
// get the PadId
Expand All @@ -646,6 +696,8 @@ Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@param {Boolean} publicStatus the public status of the pad
*/
exports.setPublicStatus = async (padID, publicStatus) => {
// ensure this is a group pad
Expand All @@ -669,6 +721,7 @@ Example returns:
{code: 0, message:"ok", data: {publicStatus: true}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.getPublicStatus = async (padID) => {
// ensure this is a group pad
Expand All @@ -686,6 +739,7 @@ Example returns:
{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
*/
exports.listAuthorsOfPad = async (padID) => {
// get the pad
Expand Down Expand Up @@ -715,6 +769,8 @@ Example returns:
{code: 0, message:"ok"}
{code: 1, message:"padID does not exist"}
@param {String} padID the id of the pad
@param {String} msg the message to send
*/

exports.sendClientsMessage = async (padID, msg) => {
Expand All @@ -740,6 +796,8 @@ Example returns:
{code: 0, message:"ok", data: {chatHead: 42}}
{code: 1, message:"padID does not exist", data: null}
@param {String} padID the id of the pad
@return {Promise<{chatHead: number}>} the chatHead of the pad
*/
exports.getChatHead = async (padID) => {
// get the pad
Expand All @@ -763,7 +821,9 @@ Example returns:
}
}
{"code":4,"message":"no or wrong API Key","data":null}
@param {String} padID the id of the pad
@param {Number} startRev the start revision number
@param {Number} endRev the end revision number
*/
exports.createDiffHTML = async (padID, startRev, endRev) => {
// check if startRev is a number
Expand All @@ -779,11 +839,9 @@ exports.createDiffHTML = async (padID, startRev, endRev) => {
// get the pad
const pad = await getPadSafe(padID, true);
const headRev = pad.getHeadRevisionNumber();
if (startRev > headRev)
startRev = headRev;
if (startRev > headRev) startRev = headRev;

if (endRev > headRev)
endRev = headRev;
if (endRev > headRev) endRev = headRev;

let padDiff;
try {
Expand All @@ -810,7 +868,6 @@ exports.createDiffHTML = async (padID, startRev, endRev) => {
{"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}
{"code":4,"message":"no or wrong API Key","data":null}
*/

exports.getStats = async () => {
const sessionInfos = padMessageHandler.sessioninfos;

Expand Down
Loading

0 comments on commit ff1b929

Please sign in to comment.