Improve jsdoc (denoland/deno_std#277)

Original: 1805c18ac7

datetime/mod.ts

@@ -3,10 +3,9 @@ export type DateFormat = "mm-dd-yyyy" | "dd-mm-yyyy" | "yyyy-mm-dd";
 
 /**
  * Parse date from string using format string
- *
+ * @param dateStr Date string
- * @param {string} dateStr - date string
+ * @param format Format string
- * @param {DateFormat} format - format string
+ * @return Parsed date
- * @return {Date} Parsed date
  */
 export function parseDate(dateStr: string, format: DateFormat): Date {
   let m, d, y: string;
@@ -42,10 +41,9 @@ export type DateTimeFormat =
 
 /**
  * Parse date & time from string using format string
- *
+ * @param dateStr Date & time string
- * @param {string} dateStr - date & time string
+ * @param format Format string
- * @param {DateTimeFormat} format - format string
+ * @return Parsed date
- * @return {Date} Parsed date
  */
 export function parseDateTime(
   datetimeStr: string,
@@ -88,9 +86,9 @@ export function parseDateTime(
 
 /**
  * Get number of the day in the year
- * @return {number} Number of the day in year
+ * @return Number of the day in year
  */
-export function dayOfYear(date: Date): any {
+export function dayOfYear(date: Date): number {
   const dayMs = 1000 * 60 * 60 * 24;
   const yearStart = new Date(date.getFullYear(), 0, 0);
   const diff =
@@ -102,8 +100,7 @@ export function dayOfYear(date: Date): any {
 
 /**
  * Get number of current day in year
- *
+ * @return Number of current day in year
- * @return {number} Number of current day in year
  */
 export function currentDayOfYear(): number {
   return dayOfYear(new Date());

fs/empty_dir.ts

@@ -4,9 +4,6 @@
  * Deletes directory contents if the directory is not empty.
  * If the directory does not exist, it is created.
  * The directory itself is not deleted.
- * @export
- * @param {string} dir
- * @returns {Promise<void>}
  */
 export async function emptyDir(dir: string): Promise<void> {
   let items: Deno.FileInfo[] = [];
@@ -30,9 +27,6 @@ export async function emptyDir(dir: string): Promise<void> {
  * Deletes directory contents if the directory is not empty.
  * If the directory does not exist, it is created.
  * The directory itself is not deleted.
- * @export
- * @param {string} dir
- * @returns {void}
  */
 export function emptyDirSync(dir: string): void {
   let items: Deno.FileInfo[] = [];

fs/ensure_dir.ts

@@ -1,9 +1,8 @@
 // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
+
 /**
- * Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
+ * Ensures that the directory exists.
- * @export
+ * If the directory structure does not exist, it is created. Like mkdir -p.
- * @param {string} dir
- * @returns {Promise<void>}
  */
 export async function ensureDir(dir: string): Promise<void> {
   try {
@@ -16,10 +15,8 @@ export async function ensureDir(dir: string): Promise<void> {
 }
 
 /**
- * Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
+ * Ensures that the directory exists.
- * @export
+ * If the directory structure does not exist, it is created. Like mkdir -p.
- * @param {string} dir
- * @returns {void}
  */
 export function ensureDirSync(dir: string): void {
   try {

fs/ensure_file.ts

@@ -1,12 +1,11 @@
 // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
 import * as path from "./path/mod.ts";
 import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
+
 /**
  * Ensures that the file exists.
- * If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOT MODIFIED.
+ * If the file that is requested to be created is in directories that do not exist,
- * @export
+ * these directories are created. If the file already exists, it is NOT MODIFIED.
- * @param {string} filePath
- * @returns {Promise<void>}
  */
 export async function ensureFile(filePath: string): Promise<void> {
   try {
@@ -23,10 +22,8 @@ export async function ensureFile(filePath: string): Promise<void> {
 
 /**
  * Ensures that the file exists.
- * If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOT MODIFIED.
+ * If the file that is requested to be created is in directories that do not exist,
- * @export
+ * these directories are created. If the file already exists, it is NOT MODIFIED.
- * @param {string} filePath
- * @returns {void}
  */
 export function ensureFileSync(filePath: string): void {
   try {

fs/exists.ts

@@ -1,22 +1,13 @@
 // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
-/**
+
- * Test whether or not the given path exists by checking with the file system
+/** Test whether or not the given path exists by checking with the file system */
- * @export
- * @param {string} filePath
- * @returns {Promise<boolean>}
- */
 export async function exists(filePath: string): Promise<boolean> {
   return Deno.stat(filePath)
     .then(() => true)
     .catch(() => false);
 }
 
-/**
+/** Test whether or not the given path exists by checking with the file system */
- * Test whether or not the given path exists by checking with the file system
- * @export
- * @param {string} filePath
- * @returns {boolean}
- */
 export function existsSync(filePath: string): boolean {
   try {
     Deno.statSync(filePath);

fs/globrex.ts

@@ -23,14 +23,14 @@ export interface GlobrexResult {
 
 /**
  * Convert any glob pattern to a JavaScript Regexp object
- * @param {String} glob Glob pattern to convert
+ * @param glob Glob pattern to convert
- * @param {Object} opts Configuration object
+ * @param opts Configuration object
- * @param {Boolean} [opts.extended=false] Support advanced ext globbing
+ * @param [opts.extended=false] Support advanced ext globbing
- * @param {Boolean} [opts.globstar=false] Support globstar
+ * @param [opts.globstar=false] Support globstar
- * @param {Boolean} [opts.strict=true] be laissez faire about mutiple slashes
+ * @param [opts.strict=true] be laissez faire about mutiple slashes
- * @param {Boolean} [opts.filepath=''] Parse as filepath for extra path related features
+ * @param [opts.filepath=""] Parse as filepath for extra path related features
- * @param {String} [opts.flags=''] RegExp globs
+ * @param [opts.flags=""] RegExp globs
- * @returns {Object} converted object with string, segments and RegExp object
+ * @returns Converted object with string, segments and RegExp object
  */
 export function globrex(
   glob: string,

fs/move.ts

@@ -15,14 +15,7 @@ function isSrcSubdir(src: string, dest: string): boolean {
   }, true);
 }
 
-/**
+/** Moves a file or directory */
- * Moves a file or directory
- * @export
- * @param {string} src
- * @param {string} dest
- * @param {MoveOptions} [options]
- * @returns {Promise<void>}
- */
 export async function move(
   src: string,
   dest: string,
@@ -52,14 +45,7 @@ export async function move(
   return;
 }
 
-/**
+/** Moves a file or directory */
- * Moves a file or directory
- * @export
- * @param {string} src
- * @param {string} dest
- * @param {MoveOptions} [options]
- * @returns {void}
- */
 export function moveSync(
   src: string,
   dest: string,

fs/read_json.ts

@@ -1,12 +1,7 @@
 // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
 import * as path from "./path/mod.ts";
 
-/**
+/** Reads a JSON file and then parses it into an object */
- * Reads a JSON file and then parses it into an object
- * @export
- * @param {string} filePath
- * @returns {Promise<any>}
- */
 export async function readJson(filePath: string): Promise<any> {
   filePath = path.resolve(filePath);
   const decoder = new TextDecoder("utf-8");
@@ -21,12 +16,7 @@ export async function readJson(filePath: string): Promise<any> {
   }
 }
 
-/**
+/** Reads a JSON file and then parses it into an object */
- * Reads a JSON file and then parses it into an object
- * @export
- * @param {string} filePath
- * @returns {void}
- */
 export function readJsonSync(filePath: string): any {
   filePath = path.resolve(filePath);
   const decoder = new TextDecoder("utf-8");