Skip to content

Commit

Permalink
Merge pull request KatChaotic#40 from soft-decay/master
Browse files Browse the repository at this point in the history 
fix(v3-parser): Export metadata for method.param items (KatChaotic#39)
  • Loading branch information
@alexprey
alexprey authored Nov 30, 2020
2 parents 9282ac5 + c1eeb18 commit afb6115
Show file tree
Hide file tree
Showing 12 changed files with 139 additions and 264 deletions.
15 changes: 11 additions & 4 deletions examples/Button.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@
"keywords": [
{
"name": "param",
"description": "{string} question a question about life, the universe, everything"
"description": "{string} [question=Why?] a question about life, the universe, everything"
},
{
"name": "returns",
Expand All @@ -142,9 +142,17 @@
"visibility": "public",
"description": "Computes the answer to your question.",
"name": "computeAnswer",
"args": [
"params": [
{
"name": "question"
"type": {
"kind": "type",
"text": "string",
"type": "string"
},
"name": "question",
"optional": true,
"default": "Why?",
"description": "a question about life, the universe, everything"
}
],
"return": {
Expand Down Expand Up @@ -176,7 +184,6 @@
"parent": "button",
"modificators": [],
"locations": null,
"loc": null,
"visibility": "public",
"description": "",
"keywords": []
Expand Down
4 changes: 2 additions & 2 deletions examples/Button.svelte
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,11 @@
/**
* Computes the answer to your question.
* @param {string} question a question about life, the universe, everything
* @param {string} [question=Why?] a question about life, the universe, everything
* @returns {number} the answer to all your questions
*/
export function computeAnswer(question) {
return question.indexOf("?") >= 0 ? 42 : 23;
return question.indexOf('?') >= 0 ? 42 : 23;
};
</script>

Expand Down
23 changes: 11 additions & 12 deletions lib/jsdoc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ const RETURN_RE = new RegExp(`^\\s*(${TYPE})?(\\s*${TYPE_DESC})?`, 'i');

const DEFAULT_TYPE = 'any';

function getDefaultJSDocType() {
return {
kind: 'type',
text: '*',
type: DEFAULT_TYPE
};
}

function parseType(type, param) {
if (type.indexOf('|') > -1) {
param.type = type.split('|');
Expand Down Expand Up @@ -111,15 +119,10 @@ function parseTypeKeyword(text) {

function parseParamKeyword(text) {
const param = {
type: {
kind: 'type',
text: '*',
type: DEFAULT_TYPE
},
type: getDefaultJSDocType(),
name: null,
optional: false,
default: null,
description: null
default: null
};

const match = PARAM_RE.exec(text);
Expand Down Expand Up @@ -169,11 +172,7 @@ function parseParamKeyword(text) {

function parseReturnKeyword(text) {
const output = {
type: {
kind: 'type',
text: '*',
type: DEFAULT_TYPE
},
type: getDefaultJSDocType(),
description: null
};
const matches = RETURN_RE.exec(text);
Expand Down
23 changes: 3 additions & 20 deletions lib/parser.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,6 @@ class Parser extends EventEmitter {
start: p.key.start + this.scriptOffset,
end: p.key.end + this.scriptOffset
}];
entry.loc = entry.locations[0];
}
}

Expand Down Expand Up @@ -223,13 +222,13 @@ class Parser extends EventEmitter {
} else if (property.key.name === 'components') {
if (p.value && p.value.type === 'Identifier') {
if (hasOwnProperty(this.imports, p.value.name)) {
// TODO: 3.*, Backward compatibility: Remove this property
entry.importPath = this.imports[p.value.name].sourceFilename;
entry.value = entry.importPath;
}
}
} else if (entry.value instanceof utils.NodeFunction) {
entry.args = entry.value.params.map((param) => param.name);
entry.params = entry.value.params.map(
(param) => ({ name: param.name })
);
} else if (property.key.name === 'data') {
const typeKeyword = entry.keywords.find(kw => kw.name === 'type');

Expand Down Expand Up @@ -524,8 +523,6 @@ class Parser extends EventEmitter {
start: next.start + this.scriptOffset,
end: next.end + this.scriptOffset
}];
// TODO: Deprication - Remove this property with V3.*
event.loc = event.locations[0];
}
}

Expand Down Expand Up @@ -612,8 +609,6 @@ class Parser extends EventEmitter {
start: parser.startIndex,
end: parser.endIndex
}];
// TODO: Deprication - Remove this property with V3.*
slot.loc = slot.locations[0];
}

this.emit('slot', slot);
Expand All @@ -627,10 +622,6 @@ class Parser extends EventEmitter {
parent: tagName,
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? [lastAttributeLocations[name]]
: null,
// TODO: Deprication - Remove this property with V3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? lastAttributeLocations[name]
: null
}));

Expand Down Expand Up @@ -669,10 +660,6 @@ class Parser extends EventEmitter {
modificators: nameWithModificators.slice(1),
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? [lastAttributeLocations[name]]
: null,
// TODO: Deprication - Remove this property with V3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? lastAttributeLocations[name]
: null
};
});
Expand All @@ -693,10 +680,6 @@ class Parser extends EventEmitter {
parent: null,
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? [lastAttributeLocations[name]]
: null,
// TODO: Deprication - Remove this property with V3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? lastAttributeLocations[name]
: null
};
})
Expand Down
95 changes: 48 additions & 47 deletions lib/v3/parser.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,16 @@ const SCOPE_DEFAULT = 'default';
const SCOPE_STATIC = 'static';
const SCOPE_MARKUP = 'markup';

const PARAM_ALIASES = {
arg: true,
argument: true,
param: true
};
const RETURN_ALIASES = {
return: true,
returns: true,
};

class Parser extends EventEmitter {
constructor(structure, options) {
super();
Expand Down Expand Up @@ -133,9 +143,6 @@ class Parser extends EventEmitter {
start: variable.location.start + parseContext.offset,
end: variable.location.end + parseContext.offset,
}];

// TODO: Deprication - remove after 3.*
item.loc = item.locations[0];
}

this.updateType(item);
Expand All @@ -150,7 +157,7 @@ class Parser extends EventEmitter {

const item = Object.assign({}, comment, {
name: method.name,
args: method.args,
params: method.params,
return: method.return,
static: parseContext.scopeType === SCOPE_STATIC
});
Expand All @@ -160,9 +167,6 @@ class Parser extends EventEmitter {
start: method.location.start + parseContext.offset,
end: method.location.end + parseContext.offset
}];

// TODO: Deprication - remove after 3.*
item.loc = item.locations[0];
}

this.emit('method', item);
Expand All @@ -180,9 +184,6 @@ class Parser extends EventEmitter {
start: computed.location.start + parseContext.offset,
end: computed.location.end + parseContext.offset
}];

// TODO: Deprication - remove after 3.*
item.loc = item.locations[0];
}

this.updateType(item);
Expand All @@ -200,9 +201,6 @@ class Parser extends EventEmitter {
start: event.location.start + parseContext.offset,
end: event.location.end + parseContext.offset
}];

// TODO: Deprication - remove after 3.*
item.loc = item.locations[0];
}

this.emit('event', item);
Expand All @@ -220,17 +218,13 @@ class Parser extends EventEmitter {
const item = Object.assign({}, utils.getCommentFromSourceCode(component.node, parseContext.sourceCode, { defaultVisibility: 'private' }), {
name: component.name,
importPath: component.path,
// TODO: 3.*, Backward compatibility: Remove this property
value: component.path
});

if (this.includeSourceLocations && component.location) {
item.locations = [{
start: component.location.start + parseContext.offset,
end: component.location.end + parseContext.offset
}];
// TODO: 3.*, Backward compatibility: Remove this property
item.loc = item.locations[0];
}

this.emit('component', item);
Expand Down Expand Up @@ -389,6 +383,7 @@ class Parser extends EventEmitter {

if (declaration.type === 'FunctionDeclaration') {
const func = this.parseFunctionDeclaration(declaration);

this.emitMethodItem(func, parseContext, 'public', exportNodeComment);

if (declaration.body) {
Expand Down Expand Up @@ -679,11 +674,11 @@ class Parser extends EventEmitter {
throw new Error('Node should have a FunctionDeclarationType, but is ' + node.type);
}

const args = [];
const params = [];

node.params.forEach(param => {
node.params.forEach((param) => {
if (param.type === 'Identifier') {
args.push({
params.push({
name: param.name,
});
}
Expand All @@ -696,7 +691,7 @@ class Parser extends EventEmitter {
start: node.id.start,
end: node.id.end
},
args: args,
params: params,
};

return output;
Expand Down Expand Up @@ -755,10 +750,6 @@ class Parser extends EventEmitter {
modificators: nameWithModificators.slice(1),
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? [lastAttributeLocations[name]]
: null,
// TODO: Deprication, remove this property with 3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? lastAttributeLocations[name]
: null
};

Expand Down Expand Up @@ -859,10 +850,6 @@ class Parser extends EventEmitter {
parent: tagName,
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? [lastAttributeLocations[name]]
: null,
// TODO: Reprication, remove this property with 3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, name)
? lastAttributeLocations[name]
: null
};
});
Expand All @@ -876,8 +863,6 @@ class Parser extends EventEmitter {
property: bindProperty.sourcePropertyName
}],
locations: bindProperty.locations,
// TODO: Reprication, remove this property with 3.*
loc: bindProperty.loc,
visibility: 'private',
static: false,
readonly: false
Expand All @@ -896,10 +881,6 @@ class Parser extends EventEmitter {
parent: tagName,
locations: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, 'bind:this')
? [lastAttributeLocations['bind:this']]
: null,
// TODO: Reprication, remove this property with 3.*
loc: this.includeSourceLocations && hasOwnProperty(lastAttributeLocations, 'bind:this')
? lastAttributeLocations['bind:this']
: null
});
}
Expand All @@ -916,21 +897,41 @@ class Parser extends EventEmitter {
parser.end();
}

/**
* Mutates event.
* @param {any[]} keywords
* @param {{ params?: any[] }} event
*/
parseKeywords(keywords = [], event) {
event.params = [];
if (!event.params) {
event.params = [];
}

keywords.forEach(({ name, description }) => {
switch (name) {
case 'arg':
case 'param':
case 'argument':
event.params.push(jsdoc.parseParamKeyword(description));
break;

case 'return':
case 'returns':
event.return = jsdoc.parseReturnKeyword(description);
break;
if (name in PARAM_ALIASES) {
const parsedParam = jsdoc.parseParamKeyword(description);
const pIndex = event.params.findIndex(
p => p.name === parsedParam.name
);

/*
* Replace the param if there is already one present with
* the same name. This will happen with parsed
* FunctionDeclaration because params will already be
* present from parsing the AST node.
*/
if (pIndex >= 0) {
event.params[pIndex] = parsedParam;
} else {
/*
* This means @param does not match an actual param
* in the FunctionDeclaration.
* TODO: Implement option to choose behaviour (keep, ignore, warn, throw)
*/
event.params.push(parsedParam);
}
} else if (name in RETURN_ALIASES) {
event.return = jsdoc.parseReturnKeyword(description);
}
});

Expand Down
Loading

0 comments on commit afb6115

Please sign in to comment.