Implement Resolves comment

Closes: #77

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to
 - Support generating contents table for API.
 - Support for nested fields of properties.
 - Support adding namespace prefix to the entities names.
+- Implement `Resolves` comment. It can be used to specify what async function or
+  Promise will resolve.
 
 ### Changed
 

lib/generator.js

@@ -230,7 +230,9 @@ const getNativeArgs = str =>
 
 const getSignatures = (name, sig) => {
   const defaultArgs = sig.parameters
-    .filter(p => p.offset === 2 && p.name !== 'Returns:')
+    .filter(
+      p => p.offset === 2 && p.name !== 'Returns:' && p.name !== 'Resolves:'
+    )
     .map(p => p.name);
   let signatures = [defaultArgs];
 
@@ -253,6 +255,9 @@ const getSignatures = (name, sig) => {
   return signatures;
 };
 
+const findComment = (comments, name) =>
+  comments.find(comment => comment.name === name);
+
 const getPropsParams = comment =>
   comment.parameters.reduce((props, prop) => {
     if (prop.offset === CODE_PARAMS_OFFSET) {
@@ -317,7 +322,7 @@ const generateParameters = (parameters, opts) => {
     }
 
     let line;
-    if (parameter.name === 'Returns:') {
+    if (parameter.name === 'Returns:' || parameter.name === 'Resolves:') {
       line = '- _' + parameter.name + (types ? '_ ' : '_');
     } else {
       line = '- `' + parameter.name + (types ? '`: ' : '`');
@@ -330,8 +335,7 @@ const generateParameters = (parameters, opts) => {
   return buf;
 };
 
-const generateReturns = (comments, opts) => {
-  const comment = comments.find(comment => comment.name === 'Returns');
+const genCommentWithParams = (comment, opts) => {
   if (!comment) return [];
 
   const typeLine = genTypeLine(comment, opts);
@@ -340,6 +344,12 @@ const generateReturns = (comments, opts) => {
   return [line, '', ...res];
 };
 
+const generateReturns = (comments, opts) =>
+  genCommentWithParams(findComment(comments, 'Returns'), opts);
+
+const generateResolves = (comments, opts) =>
+  genCommentWithParams(findComment(comments, 'Resolves'), opts);
+
 const generateTitle = (sig, opts) => {
   if (!sig.title) return [];
   const title = wrapComment(sig.title, opts);
@@ -372,7 +382,7 @@ const generateRestComments = (comments, opts) => {
 
 const generateStaticProperties = (method, comments, opts) => {
   const buf = [];
-  const comment = comments.find(comm => comm.name === 'Static properties');
+  const comment = findComment(comments, 'Static properties');
   if (!comment) return buf;
 
   const params = getPropsParams(comment);
@@ -399,7 +409,7 @@ const generateStaticProperties = (method, comments, opts) => {
 
 const generateProperties = (method, comments, opts) => {
   const buf = [];
-  const comment = comments.find(comm => comm.name === 'Properties');
+  const comment = findComment(comments, 'Properties');
   if (!comment) return buf;
 
   const params = getPropsParams(comment);
@@ -430,6 +440,7 @@ const generateFunction = (name, sig, opts, methods) => {
     ...generateSignatures(name, sig, opts, methods),
     ...generateParameters(sig.parameters, opts),
     ...generateReturns(sig.comments, opts),
+    ...generateResolves(sig.comments, opts),
     ...generateTitle(sig, opts),
     ...generateDescription(sig, opts),
     ...generateRestComments(sig.comments, opts),

lib/introspector.js

@@ -6,6 +6,7 @@ const ALL_TYPES = new Set(types.ALL_TYPES);
 
 const NAMED_LINES = [
   'Returns:', // returned value
+  'Resolves:', // resolved value
   'Properties:', // class instance/function properties
   'Static properties:', // class instance/function properties
   'Example:', // example of usage
@@ -196,7 +197,7 @@ const parseRest = lines => {
     let nonStandardTypes = [];
     let parameters = null;
 
-    if (name === 'Returns') {
+    if (name === 'Returns' || name === 'Resolves') {
       [types, nonStandardTypes, comment] = parseTypes(comment.trimLeft());
       const parameterLines = [comment, ...commentLines];
       const start = parameterLines.findIndex(

test/example.js

@@ -116,7 +116,15 @@ const asyncLambda = async () => {};
 
 // Async functions are supported
 // Returns: <Promise>
-const asyncFunc = async function() {};
+// Resolves: <Object>
+//   a <number>
+//   b <string>
+const asyncFunc = async function() {
+  return {
+    a: 3,
+    b: 'abc',
+  };
+};
 
 const asyncFunc2 = async function(a) {
   console.log(a);

test/example.md

@@ -166,6 +166,11 @@ Function with no arguments
 
 _Returns:_ [`<Promise>`][promise]
 
+_Resolves:_ [`<Object>`][object]
+
+- `a`: [`<number>`][number]
+- `b`: [`<string>`][string]
+
 Async functions are supported
 
 ## async lambdas.asyncNestedFunctions.asyncFunc2(a)