Skip to content

Commit

Permalink
Put doc comments on interfaces rather than implementations
Browse files Browse the repository at this point in the history 
Makes generated API documentation more useful.
  • Loading branch information
@siddharthvp
siddharthvp committed Aug 21, 2021
1 parent dd5299d commit ebf5d2b
Show file tree
Hide file tree
Showing 10 changed files with 474 additions and 393 deletions.
62 changes: 33 additions & 29 deletions src/category.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,47 @@ type ApiPageInfo = {
};

export interface MwnCategoryStatic {
new (title: MwnTitle | string): MwnCategory;
/**
* @param {string} name - name of the category
*/
new (name: MwnTitle | string): MwnCategory;
}

export interface MwnCategory extends MwnPage {
/**
* Get all members in the category - this includes subcategories, pages and files
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 0, title: 'Main Page' }
*/
members(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]>;
membersGen(options?: ApiQueryCategoryMembersParams): AsyncGenerator<ApiPageInfo>;
/**
* Get all pages in the category - does not include subcategories or files
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 0, title: 'Main Page' }
*/
pages(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]>;
/**
* Get all subcategories of the category
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 14, title: 'Category:Living people' }
*/
subcats(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]>;
/**
* Get all files in the category
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 6, title: 'File:Image.jpg' }
*/
files(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]>;
}

export default function (bot: mwn) {
class Category extends bot.page implements MwnCategory {
/**
* @constructor
* @param {string} name - name of the category
*/
/** @inheritDoc */
constructor(name: MwnTitle | string) {
super(name, 14);
if (this.namespace !== 14) {
Expand All @@ -34,12 +58,7 @@ export default function (bot: mwn) {

// TODO: Add recursive modes

/**
* Get all members in the category - this includes subcategories, pages and files
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 0, title: 'Main Page' }
*/
/** @inheritDoc */
members(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]> {
return bot
.request({
Expand Down Expand Up @@ -67,32 +86,17 @@ export default function (bot: mwn) {
}
}

/**
* Get all pages in the category - does not include subcategories or files
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 0, title: 'Main Page' }
*/
/** @inheritDoc */
pages(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]> {
return this.members({ cmtype: ['page'], ...options });
}

/**
* Get all subcategories of the category
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 14, title: 'Category:Living people' }
*/
/** @inheritDoc */
subcats(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]> {
return this.members({ cmtype: ['subcat'], ...options });
}

/**
* Get all files in the category
* @param {Object} options - additional API parameters
* @returns {Promise<Object[]>} - Resolved with array of objects of form
* { pageid: 324234, ns: 6, title: 'File:Image.jpg' }
*/
/** @inheritDoc */
files(options?: ApiQueryCategoryMembersParams): Promise<ApiPageInfo[]> {
return this.members({ cmtype: ['file'], ...options });
}
Expand Down
128 changes: 66 additions & 62 deletions src/date.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,6 @@ import { Unbinder } from './wikitext';
* handling dates, as well as a constructor that
* can parse MediaWiki dating formats.
*/

export interface MwnDateStatic {
new (...args: any[]): MwnDate;
getMonthName(monthNum: number): string;
getMonthNameAbbrev(monthNum: number): string;
getDayName(dayNum: number): string;
getDayNameAbbrev(dayNum: number): string;
}

export interface MwnDate extends Date {
isValid(): boolean;
isBefore(date: Date | MwnDate): boolean;
Expand All @@ -27,24 +18,72 @@ export interface MwnDate extends Date {
getUTCDayNameAbbrev(): string;
getDayName(): string;
getDayNameAbbrev(): string;

/**
* Add a given number of minutes, hours, days, months or years to the date.
* This is done in-place. The modified date object is also returned, allowing chaining.
* @param {number} number - should be an integer
* @param {string} unit
* @throws {Error} if invalid or unsupported unit is given
* @returns {XDate}
*/
add(number: number, unit: timeUnit): MwnDate;

/**
* Subtracts a given number of minutes, hours, days, months or years to the date.
* This is done in-place. The modified date object is also returned, allowing chaining.
* @param {number} number - should be an integer
* @param {string} unit
* @throws {Error} if invalid or unsupported unit is given
* @returns {XDate}
*/
subtract(number: number, unit: timeUnit): MwnDate;

/**
* Formats the date into a string per the given format string.
* Replacement syntax is a subset of that in moment.js.
* @param {string} formatstr
* @param {(string|number)} [zone=utc] - 'system' (for system-default time zone),
* 'utc' (for UTC), or specify a time zone as number of minutes past UTC.
* @returns {string}
*/
format(formatstr: string, zone?: number | 'utc' | 'system'): string;

/**
* Gives a readable relative time string such as "Yesterday at 6:43 PM" or "Last Thursday at 11:45 AM".
* Similar to calendar in moment.js, but with time zone support.
* @param {(string|number)} [zone=system] - 'system' (for browser-default time zone),
* 'utc' (for UTC), or specify a time zone as number of minutes past UTC
* @returns {string}
*/
calendar(zone?: number | 'utc' | 'system'): string;
}

/**
* Wrapper around the native JS Date() for ease of
* handling dates, as well as a constructor that
* can parse MediaWiki dating formats.
*/
export interface MwnDateStatic {
/**
* Create a date object. MediaWiki timestamp format is also acceptable,
* in addition to everything that JS Date() accepts.
*/
new (...args: any[]): MwnDate;
/**
* Get month name from month number (1-indexed)
*/
getMonthName(monthNum: number): string;
/**
* Get abbreviated month name from month number (1-indexed)
*/
getMonthNameAbbrev(monthNum: number): string;
/**
* Get day name from day number (1-indexed, starting from Sunday)
*/
getDayName(dayNum: number): string;
/**
* Get abbreviated day name from day number (1-indexed, starting from Sunday)
*/
getDayNameAbbrev(dayNum: number): string;
}

export default function (bot: mwn) {
class XDate extends Date implements MwnDate {
/**
* Create a date object. MediaWiki timestamp format is also acceptable,
* in addition to everything that JS Date() accepts.
*/
constructor(...args: any[]) {
if (args.length === 1 && typeof args[0] === 'string') {
// parse MediaWiki format: YYYYMMDDHHmmss
Expand Down Expand Up @@ -123,14 +162,7 @@ export default function (bot: mwn) {
return XDate.localeData.daysShort[this.getDay()];
}

/**
* Add a given number of minutes, hours, days, months or years to the date.
* This is done in-place. The modified date object is also returned, allowing chaining.
* @param {number} number - should be an integer
* @param {string} unit
* @throws {Error} if invalid or unsupported unit is given
* @returns {XDate}
*/
/** @inheritDoc */
add(number: number, unit: timeUnit): XDate {
// @ts-ignore
let unitNorm = unitMap[unit] || unitMap[unit + 's']; // so that both singular and plural forms work
Expand All @@ -142,26 +174,12 @@ export default function (bot: mwn) {
throw new Error('Invalid unit "' + unit + '": Only ' + Object.keys(unitMap).join(', ') + ' are allowed.');
}

/**
* Subtracts a given number of minutes, hours, days, months or years to the date.
* This is done in-place. The modified date object is also returned, allowing chaining.
* @param {number} number - should be an integer
* @param {string} unit
* @throws {Error} if invalid or unsupported unit is given
* @returns {XDate}
*/
/** @inheritDoc */
subtract(number: number, unit: timeUnit): XDate {
return this.add(-number, unit);
}

/**
* Formats the date into a string per the given format string.
* Replacement syntax is a subset of that in moment.js.
* @param {string} formatstr
* @param {(string|number)} [zone=utc] - 'system' (for system-default time zone),
* 'utc' (for UTC), or specify a time zone as number of minutes past UTC.
* @returns {string}
*/
/** @inheritDoc */
format(formatstr: string, zone: number | 'utc' | 'system' = 'utc'): string {
if (!this.isValid()) {
return ''; // avoid bogus NaNs in output
Expand Down Expand Up @@ -227,13 +245,7 @@ export default function (bot: mwn) {
return unbinder.rebind().replace(/\[(.*?)\]/g, '$1');
}

/**
* Gives a readable relative time string such as "Yesterday at 6:43 PM" or "Last Thursday at 11:45 AM".
* Similar to calendar in moment.js, but with time zone support.
* @param {(string|number)} [zone=system] - 'system' (for browser-default time zone),
* 'utc' (for UTC), or specify a time zone as number of minutes past UTC
* @returns {string}
*/
/** @inheritDoc */
calendar(zone: number | 'utc' | 'system' = 'utc'): string {
// Zero out the hours, minutes, seconds and milliseconds - keeping only the date;
// find the difference. Note that setHours() returns the same thing as getTime().
Expand Down Expand Up @@ -282,30 +294,22 @@ export default function (bot: mwn) {
},
};

/**
* Get month name from month number (1-indexed)
*/
/** @inheritDoc */
static getMonthName(monthNum: number): string {
return XDate.localeData.months[monthNum - 1];
}

/**
* Get abbreviated month name from month number (1-indexed)
*/
/** @inheritDoc */
static getMonthNameAbbrev(monthNum: number): string {
return XDate.localeData.monthsShort[monthNum - 1];
}

/**
* Get day name from day number (1-indexed, starting from Sunday)
*/
/** @inheritDoc */
static getDayName(dayNum: number): string {
return XDate.localeData.days[dayNum - 1];
}

/**
* Get abbreviated day name from day number (1-indexed, starting from Sunday)
*/
/** @inheritDoc */
static getDayNameAbbrev(dayNum: number): string {
return XDate.localeData.daysShort[dayNum - 1];
}
Expand Down
14 changes: 9 additions & 5 deletions src/eventstream.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,17 @@ export interface MwnStreamStatic {
}

export interface MwnStream {
/**
* Register a function to trigger for every message data from the source.
* @param {Function | Object} [filter={}]
* @param {Function} action
*/
addListener(filter: ((data: any) => boolean) | any, action: (data: any) => void): void;
}

/**
* Represents an event in the recentchange stream.
*/
export type RecentChangeStreamEvent = {
$schema: string;
meta: {
Expand Down Expand Up @@ -117,11 +125,7 @@ export default function (bot: mwn) {
};
}

/**
* Register a function to trigger for every message data from the source.
* @param {Function | Object} [filter={}]
* @param {Function} action
*/
/** @inheritDoc */
addListener(filter: ((data: any) => boolean) | any = {}, action: (data: any) => void): void {
let filterer =
typeof filter === 'function'
Expand Down
Loading

0 comments on commit ebf5d2b

Please sign in to comment.