From 7b0809703e60306588a738a4e6b07bf7c7c098c7 Mon Sep 17 00:00:00 2001 From: Pluto Date: Sat, 26 Oct 2024 23:14:49 +0530 Subject: [PATCH] docs: refine API docs for files in File dir --- docs/API-Reference/file/FileUtils.md | 128 ++++++++++++++------------- src/file/FileUtils.js | 15 +++- 2 files changed, 80 insertions(+), 63 deletions(-) diff --git a/docs/API-Reference/file/FileUtils.md b/docs/API-Reference/file/FileUtils.md index b1d9ecf667..d5030c7317 100644 --- a/docs/API-Reference/file/FileUtils.md +++ b/docs/API-Reference/file/FileUtils.md @@ -3,28 +3,25 @@ const FileUtils = brackets.getModule("file/FileUtils") ``` - - -## list : List -of File Extensions which will be opened in external Application - -**Kind**: global variable ## LINE\_ENDINGS\_CRLF : enum -Line endings +Line endings crlf **Kind**: global enum - + -## Maximium : Number -file size (in megabytes) (for display strings) This must be a hard-coded value since this value tells how low-level APIs should behave which cannot have a load order dependency on preferences manager +## LINE\_ENDINGS\_LF : enum +Line endings lf -**Kind**: global constant +**Kind**: global enum ## Maximium : Number -file size (in bytes) This must be a hard-coded value since this value tells how low-level APIs should behave which cannot have a load order dependency on preferences manager +file size (in bytes) + This must be a hard-coded value since this value + tells how low-level APIs should behave which cannot + have a load order dependency on preferences manager **Kind**: global constant @@ -33,7 +30,9 @@ file size (in bytes) This must be a hard-coded value since this value tells Asynchronously reads a file as UTF-8 encoded text. **Kind**: global function -**Returns**: $.Promise - a jQuery promise that will be resolved with the file's text content plus its timestamp, or rejected with a FileSystemError string constant if the file can not be read. +**Returns**: $.Promise - a jQuery promise that will be resolved with the + file's text content plus its timestamp, or rejected with a FileSystemError string + constant if the file can not be read. | Param | Type | Description | | --- | --- | --- | @@ -46,7 +45,8 @@ Asynchronously reads a file as UTF-8 encoded text. Asynchronously writes a file as UTF-8 encoded text. **Kind**: global function -**Returns**: $.Promise - a jQuery promise that will be resolved when file writing completes, or rejected with a FileSystemError string constant. +**Returns**: $.Promise - a jQuery promise that will be resolved when +file writing completes, or rejected with a FileSystemError string constant. | Param | Type | Description | | --- | --- | --- | @@ -56,14 +56,15 @@ Asynchronously writes a file as UTF-8 encoded text. -## getPlatformLineEndings() ⇒ [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| LINE\_ENDINGS\_LF +## getPlatformLineEndings() ⇒ [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| [LINE\_ENDINGS\_LF](#LINE_ENDINGS_LF) Returns the standard line endings for the current platform **Kind**: global function -## sniffLineEndings(text) ⇒ null \| [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| LINE\_ENDINGS\_LF -Scans the first 1000 chars of the text to determine how it encodes line endings. Returns null if usage is mixed or if no line endings found. +## sniffLineEndings(text) ⇒ null \| [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| [LINE\_ENDINGS\_LF](#LINE_ENDINGS_LF) +Scans the first 1000 chars of the text to determine how it encodes line endings. Returns +null if usage is mixed or if no line endings found. **Kind**: global function @@ -81,7 +82,7 @@ Translates any line ending types in the given text to the be the single form spe | Param | Type | | --- | --- | | text | string | -| lineEndings | null \| [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| LINE\_ENDINGS\_LF | +| lineEndings | null \| [LINE\_ENDINGS\_CRLF](#LINE_ENDINGS_CRLF) \| [LINE\_ENDINGS\_LF](#LINE_ENDINGS_LF) | @@ -93,19 +94,6 @@ Translates any line ending types in the given text to the be the single form spe | --- | --- | | name | FileSystemError | - - -## ..showFileOpenError(name) ⇒ Dialog.. -***Deprecated*** - -Shows an error dialog indicating that the given file could not be opened due to the given error - -**Kind**: global function - -| Param | Type | -| --- | --- | -| name | FileSystemError | - ## makeDialogFileList(Array) @@ -120,7 +108,10 @@ Creates an HTML string for a list of files to be reported on, suitable for use i ## convertToNativePath(path) ⇒ string -Convert a URI path to a native path. On both platforms, this unescapes the URI On windows, URI paths start with a "/", but have a drive letter ("C:"). In this case, remove the initial "/". +Convert a URI path to a native path. +On both platforms, this unescapes the URI +On windows, URI paths start with a "/", but have a drive letter ("C:"). In this +case, remove the initial "/". **Kind**: global function @@ -131,7 +122,11 @@ Convert a URI path to a native path. On both platforms, this unescapes the URI O ## convertWindowsPathToUnixPath(path) ⇒ string -Convert a Windows-native path to use Unix style slashes. On Windows, this converts "C:\foo\bar\baz.txt" to "C:/foo/bar/baz.txt". On Mac, this does nothing, since Mac paths are already in Unix syntax. (Note that this does not add an initial forward-slash. Internally, our APIs generally use the "C:/foo/bar/baz.txt" style for "native" paths.) +Convert a Windows-native path to use Unix style slashes. +On Windows, this converts "C:\foo\bar\baz.txt" to "C:/foo/bar/baz.txt". +On Mac, this does nothing, since Mac paths are already in Unix syntax. +(Note that this does not add an initial forward-slash. Internally, our +APIs generally use the "C:/foo/bar/baz.txt" style for "native" paths.) **Kind**: global function **Returns**: string - A Unix-style path. @@ -143,7 +138,9 @@ Convert a Windows-native path to use Unix style slashes. On Windows, this conver ## stripTrailingSlash(path) ⇒ string -Removes the trailing slash from a path or URL, if it has one. Warning: this differs from the format of most paths used in Brackets! Use paths ending in "/" normally, as this is the format used by Directory.fullPath. +Removes the trailing slash from a path or URL, if it has one. +Warning: this differs from the format of most paths used in Brackets! Use paths ending in "/" +normally, as this is the format used by Directory.fullPath. **Kind**: global function @@ -157,7 +154,8 @@ Removes the trailing slash from a path or URL, if it has one. Warning: this diff Get the name of a file or a directory, removing any preceding path. **Kind**: global function -**Returns**: string - Returns the base name of a file or the name of a directory +**Returns**: string - Returns the base name of a file or the name of a +directory | Param | Type | Description | | --- | --- | --- | @@ -166,36 +164,33 @@ Get the name of a file or a directory, removing any preceding path. ## getNativeBracketsDirectoryPath() ⇒ string -Returns a native absolute path to the 'brackets' source directory. Note that this only works when run in brackets/src/index.html, so it does not work for unit tests (which is run from brackets/test/SpecRunner.html) WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/". +Returns a native absolute path to the 'brackets' source directory. +Note that this only works when run in brackets/src/index.html, so it does +not work for unit tests (which is run from brackets/test/SpecRunner.html) + +WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/". **Kind**: global function ## getNativeModuleDirectoryPath() ⇒ string -Given the module object passed to JS module define function, convert the path to a native absolute path. Returns a native absolute path to the module folder. WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/". +Given the module object passed to JS module define function, +convert the path to a native absolute path. +Returns a native absolute path to the module folder. + +WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/". **Kind**: global function ## getFileExtension(fullPath) ⇒ string -Get the file extension (excluding ".") given a path OR a bare filename. Returns "" for names with no extension. If the name starts with ".", the full remaining text is considered the extension. +Get the file extension (excluding ".") given a path OR a bare filename. +Returns "" for names with no extension. If the name starts with ".", the +full remaining text is considered the extension. **Kind**: global function -**Returns**: string - Returns the extension of a filename or empty string if the argument is a directory or a filename with no extension - -| Param | Type | Description | -| --- | --- | --- | -| fullPath | string | full path to a file or directory | - - - -## ..getSmartFileExtension(fullPath) ⇒ string.. -***Deprecated*** - -Get the file extension (excluding ".") given a path OR a bare filename. Returns "" for names with no extension. If the only `.` in the file is the first character, returns "" as this is not considered an extension. This method considers known extensions which include `.` in them. - -**Kind**: global function -**Returns**: string - Returns the extension of a filename or empty string if the argument is a directory or a filename with no extension +**Returns**: string - Returns the extension of a filename or empty string if +the argument is a directory or a filename with no extension | Param | Type | Description | | --- | --- | --- | @@ -204,7 +199,12 @@ Get the file extension (excluding ".") given a path OR a bare filename. Returns ## getRelativeFilename(basePath, filename) ⇒ string -Computes filename as relative to the basePath. For example: basePath: /foo/bar/, filename: /foo/bar/baz.txt returns: baz.txt The net effect is that the common prefix is stripped away. If basePath is not a prefix of filename, then undefined is returned. +Computes filename as relative to the basePath. For example: +basePath: /foo/bar/, filename: /foo/bar/baz.txt +returns: baz.txt + +The net effect is that the common prefix is stripped away. If basePath is not +a prefix of filename, then undefined is returned. **Kind**: global function **Returns**: string - relative path @@ -232,7 +232,8 @@ Determine if file extension is a static html file extension. Get the parent directory of a file. If a directory is passed, the SAME directory is returned. **Kind**: global function -**Returns**: string - Returns the path to the parent directory of a file or the path of a directory, including trailing "/" +**Returns**: string - Returns the path to the parent directory of a file or the path of a directory, + including trailing "/" | Param | Type | Description | | --- | --- | --- | @@ -241,7 +242,9 @@ Get the parent directory of a file. If a directory is passed, the SAME directory ## getParentPath(fullPath) ⇒ string -Get the parent folder of the given file/folder path. Differs from getDirectoryPath() when 'fullPath' is a directory itself: returns its parent instead of the original path. (Note: if you already have a FileSystemEntry, it's faster to use entry.parentPath instead). +Get the parent folder of the given file/folder path. Differs from getDirectoryPath() when 'fullPath' +is a directory itself: returns its parent instead of the original path. (Note: if you already have a +FileSystemEntry, it's faster to use entry.parentPath instead). **Kind**: global function **Returns**: string - Path of containing folder (including trailing "/"); or "" if path was the root @@ -265,7 +268,8 @@ Get the file name without the extension. Returns "" if name starts with "." ## compareFilenames(filename1, filename2, extFirst) ⇒ number -Compares 2 filenames in lowercases. In Windows it compares the names without the extension first and then the extensions to fix issue #4409 +Compares 2 filenames in lowercases. In Windows it compares the names without the +extension first and then the extensions to fix issue #4409 **Kind**: global function **Returns**: number - The result of the compare function @@ -279,10 +283,13 @@ Compares 2 filenames in lowercases. In Windows it compares the names without the ## comparePaths(path1, path2) ⇒ number -Compares two paths segment-by-segment, used for sorting. When two files share a path prefix, the less deeply nested one is sorted earlier in the list. Sorts files within the same parent folder based on `compareFilenames()`. +Compares two paths segment-by-segment, used for sorting. When two files share a path prefix, +the less deeply nested one is sorted earlier in the list. Sorts files within the same parent +folder based on `compareFilenames()`. **Kind**: global function -**Returns**: number - -1, 0, or 1 depending on whether path1 is less than, equal to, or greater than path2 according to this ordering. +**Returns**: number - -1, 0, or 1 depending on whether path1 is less than, equal to, or greater than + path2 according to this ordering. | Param | Type | | --- | --- | @@ -293,7 +300,8 @@ Compares two paths segment-by-segment, used for sorting. When two files share a ## encodeFilePath(path) ⇒ string **Kind**: global function -**Returns**: string - URI-encoded version suitable for appending to 'file:///`. It's not safe to use encodeURI() directly since it doesn't escape chars like "#". +**Returns**: string - URI-encoded version suitable for appending to 'file:///`. It's not safe to use encodeURI() + directly since it doesn't escape chars like "#". | Param | Type | Description | | --- | --- | --- | diff --git a/src/file/FileUtils.js b/src/file/FileUtils.js index 03b18a12b6..e878e97f8a 100644 --- a/src/file/FileUtils.js +++ b/src/file/FileUtils.js @@ -44,6 +44,7 @@ define(function (require, exports, module) { /** * @const {Number} Maximium file size (in megabytes) + * @private * (for display strings) * This must be a hard-coded value since this value * tells how low-level APIs should behave which cannot @@ -61,6 +62,7 @@ define(function (require, exports, module) { /** * @var {List} list of File Extensions which will be opened in external Application + * @private */ var extListToBeOpenedInExtApp = []; @@ -118,11 +120,16 @@ define(function (require, exports, module) { } /** - * Line endings + * Line endings crlf + * @enum {string} + */ + const LINE_ENDINGS_CRLF = "CRLF"; + + /** + * Line endings lf * @enum {string} */ - var LINE_ENDINGS_CRLF = "CRLF", - LINE_ENDINGS_LF = "LF"; + const LINE_ENDINGS_LF = "LF"; /** * Returns the standard line endings for the current platform @@ -203,6 +210,7 @@ define(function (require, exports, module) { /** * Shows an error dialog indicating that the given file could not be opened due to the given error + * @private * @deprecated Use DocumentCommandHandlers.showFileOpenError() instead * * @param {!FileSystemError} name @@ -352,6 +360,7 @@ define(function (require, exports, module) { * If the only `.` in the file is the first character, * returns "" as this is not considered an extension. * This method considers known extensions which include `.` in them. + * @private * @deprecated Use LanguageManager.getCompoundFileExtension() instead * * @param {string} fullPath full path to a file or directory