Better documentation

Signed-off-by: John Molakvoæ <skjnldsv@protonmail.com>
nextcloud-libraries · Jun 16, 2022 · bfeb49c · bfeb49c
1 parent 7c1cd70
commit bfeb49c
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 2 deletions.
diff --git a/lib/humanfilesize.ts b/lib/humanfilesize.ts
@@ -25,6 +25,12 @@ import { getCanonicalLocale } from '@nextcloud/l10n'
 
 const humanList = ['B', 'KB', 'MB', 'GB', 'TB'];
 
+/**
+ * Format a file size in a human-like format. e.g. 42GB
+ *
+ * @param size in bytes
+ * @param skipSmallSizes avoid rendering tiny sizes and return '< 1 KB' instead
+ */
 export function formatFileSize(size: number|string, skipSmallSizes: boolean = false): string {
 
 	if (typeof size === 'string') {

diff --git a/lib/index.ts b/lib/index.ts
@@ -22,7 +22,7 @@
  */
 
 export { formatFileSize } from './humanfilesize'
-export { FileType } from './newFileMenu'
+export { FileType, type Entry } from './newFileMenu'
 import { type Entry, getNewFileMenu, NewFileMenu } from './newFileMenu'
 
 declare global {
@@ -32,16 +32,25 @@ declare global {
 	}
 }
 
+/**
+ * Add a new menu entry to the upload manager menu
+ */
 export const addNewFileMenuEntry = function(entry: Entry) {
 	const newFileMenu = getNewFileMenu()
 	return newFileMenu.registerEntry(entry)
 }
 
+/**
+ * Remove a previously registered entry from the upload menu
+ */
 export const removeNewFileMenuEntry = function(entry: Entry | string) {
 	const newFileMenu = getNewFileMenu()
 	return newFileMenu.unregisterEntry(entry)
 }
 
+/**
+ * Get the list of registered entries from the upload menu
+ */
 export const getNewFileMenuEntries = function() {
 	const newFileMenu = getNewFileMenu()
 	return newFileMenu.getEntries()

diff --git a/lib/newFileMenu.ts b/lib/newFileMenu.ts
@@ -28,13 +28,22 @@ export enum FileType {
 }
 
 export interface Entry {
+	/** Unique ID */
 	id: string
+	/** Translatable string displayed in the menu */
 	displayName: string
+	// Default new file name
 	templateName: string
+	/**
+	 * Either iconSvgInline or iconClass must be defined
+	 * Svg as inline string. <svg><path fill="..." /></svg>
+	 */
 	iconSvgInline?: string
+	/** Existing icon css class */
 	iconClass?: string
 	fileType: FileType
-	handler: Function
+	/** Function to be run after creation */
+	handler?: Function
 }
 
 export class NewFileMenu {