Skip to content

Commit fd6bac7

Browse files
sebastian-lenzsebastian-lenz
committed
Added help and version output
1 parent d0a68fd commit fd6bac7

File tree

5 files changed

+355
-31
lines changed

5 files changed

+355
-31
lines changed

‎bin/typedoc.d.ts‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -172,11 +172,11 @@ declare module td {
172172
/**
173173
* Does the user want to display the help message?
174174
*/
175-
needsHelp: boolean;
175+
help: boolean;
176176
/**
177177
* Does the user want to know the version number?
178178
*/
179-
shouldPrintVersionOnly: boolean;
179+
version: boolean;
180180
/**
181181
* Should we hide the TypeDoc link at the end of the page?
182182
*/
@@ -315,13 +315,27 @@ declare module td {
315315
* @param inputFiles A list of source files whose documentation should be generated.
316316
* @param outputDirectory The path of the directory the documentation should be written to.
317317
*/
318-
generate(inputFiles: string[], outputDirectory: string): void;
318+
generate(inputFiles: string[], outputDirectory: string): boolean;
319319
/**
320320
* Return the version number of the loaded TypeScript compiler.
321321
*
322322
* @returns The version number of the loaded TypeScript package.
323323
*/
324324
getTypeScriptVersion(): string;
325+
/**
326+
* Print the version number.
327+
*
328+
* @return string[]
329+
*/
330+
printVersion(): string[];
331+
/**
332+
* Print some usage information.
333+
*
334+
* Taken from TypeScript (src/compiler/tsc.ts)
335+
*
336+
* @return string[]
337+
*/
338+
printUsage(): string[];
325339
}
326340
}
327341
declare module td {

‎bin/typedoc.js‎

Lines changed: 163 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,14 @@ var td;
201201
var OptionScope = td.OptionScope;
202202
td.ignoredTypeScriptOptions = [
203203
'out',
204-
'outDir'
204+
'outDir',
205+
'version',
206+
'help',
207+
'watch',
208+
'declarations',
209+
'mapRoot',
210+
'sourceMap',
211+
'removeComments'
205212
];
206213
/**
207214
* Modify ts.optionDeclarations to match TypeDoc requirements.
@@ -224,7 +231,7 @@ var td;
224231
},
225232
scope: 0 /* TypeDoc */,
226233
description: {
227-
key: 'Specifies the output mode the project is used to be compiled with.',
234+
key: "Specifies the output mode the project is used to be compiled with: 'file' or 'modules'",
228235
category: 2 /* Message */,
229236
code: 0
230237
}
@@ -243,7 +250,7 @@ var td;
243250
type: "string",
244251
scope: 0 /* TypeDoc */,
245252
description: {
246-
key: 'Specify the path to the theme that should be used.',
253+
key: "Specify the path to the theme that should be used or 'default' or 'minimal' to use built-in themes.",
247254
category: 2 /* Message */,
248255
code: 0
249256
}
@@ -337,6 +344,26 @@ var td;
337344
category: 2 /* Message */,
338345
code: 0
339346
}
347+
}, {
348+
name: "version",
349+
shortName: "v",
350+
type: "boolean",
351+
scope: 0 /* TypeDoc */,
352+
description: {
353+
key: 'Print the TypeDoc\'s version.',
354+
category: 2 /* Message */,
355+
code: 0
356+
}
357+
}, {
358+
name: "help",
359+
shortName: "h",
360+
type: "boolean",
361+
scope: 0 /* TypeDoc */,
362+
description: {
363+
key: 'Print this message.',
364+
category: 2 /* Message */,
365+
code: 0
366+
}
340367
}];
341368
/**
342369
* Holds all settings used by TypeDoc.
@@ -374,11 +401,11 @@ var td;
374401
/**
375402
* Does the user want to display the help message?
376403
*/
377-
this.needsHelp = false;
404+
this.help = false;
378405
/**
379406
* Does the user want to know the version number?
380407
*/
381-
this.shouldPrintVersionOnly = false;
408+
this.version = false;
382409
/**
383410
* Should we hide the TypeDoc link at the end of the page?
384411
*/
@@ -655,17 +682,21 @@ var td;
655682
*/
656683
Application.prototype.runFromCommandline = function () {
657684
if (this.settings.parseCommandLine(this)) {
658-
if (this.settings.shouldPrintVersionOnly) {
685+
if (this.settings.version) {
686+
sys.write(this.printVersion().join(sys.newLine));
659687
}
660-
else if (this.settings.inputFiles.length === 0 || this.settings.needsHelp) {
688+
else if (this.settings.inputFiles.length === 0 || this.settings.help) {
689+
sys.write(this.printUsage().join(sys.newLine));
661690
}
662691
else {
663-
this.log(td.Util.format('Using TypeScript %s from %s', this.getTypeScriptVersion(), td.tsPath), 0 /* Verbose */);
692+
sys.write(sys.newLine);
693+
this.log(td.Util.format('Using TypeScript %s from %s', this.getTypeScriptVersion(), td.tsPath), 1 /* Info */);
664694
this.settings.expandInputFiles();
665695
this.settings.out = td.Path.resolve(this.settings.out);
666696
this.generate(this.settings.inputFiles, this.settings.out);
667-
if (!this.hasErrors) {
668-
this.log(td.Util.format('Documentation generated at %s', this.settings.out));
697+
if (this.hasErrors) {
698+
sys.write(sys.newLine);
699+
this.log('Documentation could not be generated due to the errors above.');
669700
}
670701
}
671702
}
@@ -682,7 +713,13 @@ var td;
682713
this.hasErrors = true;
683714
}
684715
if (level != 0 /* Verbose */ || this.settings.verbose) {
685-
console.log(message);
716+
var output = '';
717+
if (level == 3 /* Error */)
718+
output += 'Error: ';
719+
if (level == 2 /* Warn */)
720+
output += 'Warning: ';
721+
output += message;
722+
sys.write(output + sys.newLine);
686723
}
687724
};
688725
/**
@@ -692,11 +729,35 @@ var td;
692729
* @param outputDirectory The path of the directory the documentation should be written to.
693730
*/
694731
Application.prototype.generate = function (inputFiles, outputDirectory) {
732+
var _this = this;
695733
var result = this.converter.convert(inputFiles, this.settings);
734+
if (result.errors && result.errors.length) {
735+
result.errors.forEach(function (error) {
736+
var output = error.file.filename;
737+
output += '(' + error.file.getLineAndCharacterFromPosition(error.start).line + ')';
738+
output += sys.newLine + ' ' + error.messageText;
739+
switch (error.category) {
740+
case 1 /* Error */:
741+
_this.log(output, 3 /* Error */);
742+
break;
743+
case 0 /* Warning */:
744+
_this.log(output, 2 /* Warn */);
745+
break;
746+
case 2 /* Message */:
747+
_this.log(output, 1 /* Info */);
748+
}
749+
});
750+
return false;
751+
}
696752
if (this.settings.json) {
697753
writeFile(this.settings.json, JSON.stringify(result.project.toObject(), null, '\t'), false);
754+
this.log(td.Util.format('JSON written to %s', this.settings.json));
698755
}
699-
this.renderer.render(result.project, outputDirectory);
756+
else {
757+
this.renderer.render(result.project, outputDirectory);
758+
this.log(td.Util.format('Documentation generated at %s', this.settings.out));
759+
}
760+
return true;
700761
};
701762
/**
702763
* Return the version number of the loaded TypeScript compiler.
@@ -707,6 +768,96 @@ var td;
707768
var json = JSON.parse(td.FS.readFileSync(td.Path.join(td.tsPath, '..', 'package.json'), 'utf8'));
708769
return json.version;
709770
};
771+
/**
772+
* Print the version number.
773+
*
774+
* @return string[]
775+
*/
776+
Application.prototype.printVersion = function () {
777+
return [
778+
'',
779+
'TypeDoc ' + Application.VERSION,
780+
'Using TypeScript ' + this.getTypeScriptVersion() + ' at ' + td.tsPath,
781+
''
782+
];
783+
};
784+
/**
785+
* Print some usage information.
786+
*
787+
* Taken from TypeScript (src/compiler/tsc.ts)
788+
*
789+
* @return string[]
790+
*/
791+
Application.prototype.printUsage = function () {
792+
var marginLength = 0;
793+
var typeDoc = prepareOptions(td.optionDeclarations);
794+
var typeScript = prepareOptions(ts.optionDeclarations, td.ignoredTypeScriptOptions);
795+
var output = this.printVersion();
796+
output.push('Usage:');
797+
output.push(' typedoc --mode modules --out path/to/documentation path/to/sourcefiles');
798+
output.push('', 'TypeDoc options:');
799+
pushDeclarations(typeDoc);
800+
output.push('', 'TypeScript options:');
801+
pushDeclarations(typeScript);
802+
output.push('');
803+
return output;
804+
function prepareOptions(optsList, exclude) {
805+
// Sort our options by their names, (e.g. "--noImplicitAny" comes before "--watch")
806+
optsList = optsList.slice();
807+
optsList.sort(function (a, b) { return ts.compareValues(a.name.toLowerCase(), b.name.toLowerCase()); });
808+
// We want our descriptions to align at the same column in our output,
809+
// so we keep track of the longest option usage string.
810+
var usageColumn = []; // Things like "-d, --declaration" go in here.
811+
var descriptionColumn = [];
812+
for (var i = 0; i < optsList.length; i++) {
813+
var option = optsList[i];
814+
if (exclude && exclude.indexOf(option.name) != -1)
815+
continue;
816+
// If an option lacks a description,
817+
// it is not officially supported.
818+
if (!option.description) {
819+
continue;
820+
}
821+
var usageText = " ";
822+
if (option.shortName) {
823+
usageText += "-" + option.shortName;
824+
usageText += getParamName(option);
825+
usageText += ", ";
826+
}
827+
usageText += "--" + option.name;
828+
usageText += getParamName(option);
829+
usageColumn.push(usageText);
830+
descriptionColumn.push(option.description.key);
831+
// Set the new margin for the description column if necessary.
832+
marginLength = Math.max(usageText.length, marginLength);
833+
}
834+
return { usage: usageColumn, description: descriptionColumn };
835+
}
836+
// Special case that can't fit in the loop.
837+
function addFileOption(columns) {
838+
var usageText = " @<file>";
839+
columns.usage.push(usageText);
840+
columns.description.push(ts.Diagnostics.Insert_command_line_options_and_files_from_a_file.key);
841+
marginLength = Math.max(usageText.length, marginLength);
842+
}
843+
// Print out each row, aligning all the descriptions on the same column.
844+
function pushDeclarations(columns) {
845+
for (var i = 0; i < columns.usage.length; i++) {
846+
var usage = columns.usage[i];
847+
var description = columns.description[i];
848+
output.push(usage + makePadding(marginLength - usage.length + 2) + description);
849+
}
850+
}
851+
function getParamName(option) {
852+
if (option.paramName !== undefined) {
853+
return " " + option.paramName;
854+
}
855+
return "";
856+
}
857+
function makePadding(paddingLength) {
858+
return Array(paddingLength + 1).join(" ");
859+
}
860+
};
710861
/**
711862
* The version number of TypeDoc.
712863
*/

‎examples/basic/src/modules.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,6 @@ var objectLiteral = {
7777

7878
var typeLiteral:{
7979
():string;
80-
[name:string]:string;
8180
valueZ:string;
8281
valueY:{():string;};
8382
valueX:{

0 commit comments

Comments
 (0)