Skip to content

Commit 20da9af

Browse files
author
nickpape-msft
authored
Improve documentation and remove a few private things from the public API (microsoft#58)
* Improve documentation and remove a few private things from the public API * Changefile * Add a few more jsdoc comments * PR feedback
1 parent 077193f commit 20da9af

12 files changed

Lines changed: 339 additions & 327 deletions

‎common/changes/nickpape-improve-api_2017-01-20-00-27.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/gulp-core-build",
5+
"comment": "Remove several logging utilities from the public API and improve documentation in other places.",
6+
"type": "minor"
7+
}
8+
],
9+
"email": "nickpape@microsoft.com"
10+
}

‎common/reviews/api/gulp-core-build.api.ts‎

Lines changed: 12 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,67 @@
1-
// (undocumented)
21
export function addSuppression(str: string): void;
32

4-
// (undocumented)
5-
class CleanTask extends GulpTask<ICleanConfig> {
6-
// (undocumented)
3+
class CleanTask extends GulpTask<void> {
4+
constructor();
75
public executeTask(gulp: gulp.Gulp,
86
completeCallback: (result?: Object) => void): void;
9-
// (undocumented)
10-
public name: string;
11-
// (undocumented)
12-
public taskConfig: ICleanConfig;
137
}
148

159
class CopyTask extends GulpTask<ICopyConfig> {
16-
// (undocumented)
10+
constructor();
1711
public executeTask(gulp: gulp.Gulp,
1812
completeCallback: (result?: Object) => void): Promise<Object> | NodeJS.ReadWriteStream | void;
19-
// (undocumented)
13+
// @internal
2014
public loadSchema(): Object;
21-
// (undocumented)
22-
public taskConfig: ICopyConfig;
2315
}
2416

25-
// (undocumented)
2617
export function coverageData(coverage: number, threshold: number, filePath: string): void;
2718

28-
// (undocumented)
29-
export function endTaskSrc(taskName: string, startHrtime: [number, number], fileCount: number): void;
30-
31-
// (undocumented)
3219
export function error(...args: Array<string | Chalk.ChalkChain>): void;
3320

34-
// (undocumented)
3521
export function fileError(taskName: string, filePath: string, line: number, column: number, errorCode: string, message: string): void;
3622

37-
// (undocumented)
3823
export function fileLog(write: (text: string) => void, taskName: string, filePath: string, line: number, column: number, errorCode: string, message: string): void;
3924

40-
// (undocumented)
4125
export function fileWarning(taskName: string, filePath: string, line: number, column: number, errorCode: string, message: string): void;
4226

43-
// (undocumented)
4427
export function functionalTestRun(name: string, result: TestResultState, duration: number): void;
4528

46-
// (undocumented)
47-
export function generateGulpError(error: Object): Object;
48-
49-
class GenerateShrinkwrapTask extends GulpTask<{}> {
50-
// (undocumented)
51-
public executeTask(gulp: gulpType.Gulp): NodeJS.ReadWriteStream;
52-
// (undocumented)
53-
public name: string;
29+
class GenerateShrinkwrapTask extends GulpTask<void> {
30+
constructor();
31+
public executeTask(gulp: gulpType.Gulp, completeCallback: (result?: Object) => void): NodeJS.ReadWriteStream;
5432
}
5533

5634
export function getConfig(): IBuildConfig;
5735

58-
// (undocumented)
5936
export function getErrors(): string[];
6037

61-
// (undocumented)
62-
export function getStart(): [number, number];
63-
64-
// (undocumented)
6538
export function getWarnings(): string[];
6639

67-
// (undocumented)
68-
export function getWatchMode(): boolean;
69-
70-
// (undocumented)
7140
class GulpTask<TASK_CONFIG> implements IExecutable {
7241
protected _getConfigFilePath(): string;
73-
protected _readCommentedJsonFile(filename: string): TASK_CONFIG;
74-
// (undocumented)
7542
public buildConfig: IBuildConfig;
76-
// (undocumented)
7743
public cleanMatch: string[];
78-
// (undocumented)
7944
public copyFile(localSourcePath: string, localDestPath?: string): void;
80-
// (undocumented)
8145
public execute(config: IBuildConfig): Promise<void>;
82-
// (undocumented)
8346
public abstract executeTask(gulp: gulp.Gulp | GulpProxy, completeCallback?: (result?: Object) => void): Promise<Object> | NodeJS.ReadWriteStream | void;
84-
// (undocumented)
8547
public fileError(filePath: string, line: number, column: number, errorCode: string, message: string): void;
86-
// (undocumented)
8748
public fileExists(localPath: string): boolean;
88-
// (undocumented)
89-
public fileWarning(filePath: string, line: number, column: number, errorCode: string, message: string): void;
90-
// (undocumented)
49+
public fileWarning(filePath: string, line: number, column: number, warningCode: string, message: string): void;
9150
public getCleanMatch(buildConfig: IBuildConfig, taskConfig: TASK_CONFIG = this.taskConfig): string[];
92-
// (undocumented)
9351
public isEnabled(buildConfig: IBuildConfig): boolean;
94-
public loadSchema(): Object;
95-
// (undocumented)
52+
protected loadSchema(): Object;
9653
public log(message: string): void;
97-
// (undocumented)
9854
public logError(message: string): void;
99-
// (undocumented)
10055
public logVerbose(message: string): void;
101-
// (undocumented)
10256
public logWarning(message: string): void;
10357
public mergeConfig(taskConfig: TASK_CONFIG): void;
104-
// (undocumented)
10558
public name: string;
106-
// (undocumented)
10759
public onRegister(): void;
108-
// (undocumented)
10960
public readJSONSync(localPath: string): Object;
11061
public replaceConfig(taskConfig: TASK_CONFIG): void;
111-
// (undocumented)
11262
public resolvePath(localPath: string): string;
11363
public readonly schema: Object;
11464
public setConfig(taskConfig: TASK_CONFIG): void;
115-
// (undocumented)
11665
public taskConfig: TASK_CONFIG;
11766
}
11867

@@ -147,11 +96,6 @@ interface IBuildConfig {
14796
verbose?: boolean;
14897
}
14998

150-
// (undocumented)
151-
interface ICleanConfig {
152-
}
153-
154-
// (undocumented)
15599
interface ICopyConfig {
156100
copyTo: {
157101
// (undocumented)
@@ -186,28 +130,15 @@ interface ISchemaValidatorResult {
186130
name?: string;
187131
}
188132

189-
// (undocumented)
190-
export function log(...args: Array<string | Chalk.ChalkChain>): void;
191-
192-
// (undocumented)
193-
export function logEndSubtask(name: string, startTime: [number, number], errorObject?: Error): void;
194-
195-
// (undocumented)
196-
export function logStartSubtask(name: string): void;
197-
198-
// (undocumented)
199133
export function logSummary(value: string): void;
200134

201-
// (undocumented)
202-
export function markTaskCreationTime(): void;
203-
204135
export function mergeConfig(config: IBuildConfig): void;
205136

206137
export function parallel(...tasks: Array<IExecutable[] | IExecutable>): IExecutable;
207138

208139
export function replaceConfig(config: IBuildConfig): void;
209140

210-
// (undocumented)
141+
// @internal
211142
export function reset(): void;
212143

213144
class SchemaValidator {
@@ -223,17 +154,10 @@ export function serial(...tasks: Array<IExecutable[] | IExecutable>): IExecutabl
223154

224155
export function setConfig(config: IBuildConfig): void;
225156

226-
// (undocumented)
227-
export function setExitCode(exitCode: number): void;
228-
229-
// (undocumented)
230-
export function setWatchMode(): void;
231-
232157
export function subTask(taskName: string, fn: ICustomGulpTask): IExecutable;
233158

234159
export function task(taskName: string, task: IExecutable): IExecutable;
235160

236-
// (undocumented)
237161
enum TestResultState {
238162
// (undocumented)
239163
Failed,
@@ -245,22 +169,15 @@ enum TestResultState {
245169
Skipped
246170
}
247171

248-
class ValidateShrinkwrapTask extends GulpTask<{}> {
249-
// (undocumented)
172+
class ValidateShrinkwrapTask extends GulpTask<void> {
173+
constructor();
250174
public executeTask(gulp: gulpType.Gulp): NodeJS.ReadWriteStream;
251-
// (undocumented)
252-
public name: string;
253175
}
254176

255-
// (undocumented)
256177
export function verbose(...args: Array<string | Chalk.ChalkChain>): void;
257178

258-
// (undocumented)
259179
export function warn(...args: Array<string | Chalk.ChalkChain>): void;
260180

261181
export function watch(watchMatch: string | string[], task: IExecutable): IExecutable;
262182

263-
// (undocumented)
264-
export function writeError(e: any): void;
265-
266183
// WARNING: Unsupported export: clean

0 commit comments

Comments
 (0)