Strange results

[stefanwalther]

Hi,

using version 3.9 (as helper-apidocs is using) the following code delivers completely strange results:

'use strict';
var fs = require( 'fs' );
var path = require( 'path' );
var Q = require( 'q' );
var extend = require( 'extend-shallow' );
var glob = require( "glob" );

/**
 * Retrieve the meta information of bla bla bla
 * @returns {{fromFolder: Function, fromFile: Function}}
 * @constructor
 * @api public
 */
var ExtInfo = function () {

    return {

        /**
         * Retrieve the extension meta information from a folder.         *
         * Doesn't search recursively, just in the root of the folder for any file matching the pattern *.qext
         *
         * @exception
         * Throws an exception in the following cases:
         * - More than one qext files in the folder
         * - content of the .qext file is not valid json
         * - property `type` is missing
         *
         * @returns {object} extension meta information.
         * @param folderPath Absolute path of the folder to search in.
         *
         * @api public

         * @todo - if ending slash is missing, the path is not recognized as a valid directory
         */
        fromDir: function ( folderPath ) {

            return 'xx';

        },

        /**
         * Retrieve meta information by pointing directly to the .qext file.
         * @param filePath Absolute path of the file to fetch the meta data from.
         * @throws
         *  - File doesn\'t exist in case of pointing to a non existing file
         * @returns {promise|*|Q.promise}
         *
         * @api public
         */
        fromFile: function ( filePath ) {

            return 'y';
        }
    };
};

module.exports = new ExtInfo();

[jonschlinkert]

can you post an example of the results? Here are a few of things that might help in the meantime:

• code examples should be in gfm (markdown) fenced code blocks
• don't put anything after @return
• consider using a custom template. The current one only renders specific properties in a specific format.

I really need to do docs for this, but I haven't because @doowb and I have planned on doing a complete re-write of the parser. and we finally got a good start on it recently.

let me know if any of this helps. thanks for creating the issue

[stefanwalther]

The pure results (based on the code above) looks like this:

ExtInfo

• returns: {{fromFolder: Function, fromFile: Function}}

Retrieve the meta information of bla bla bla

.exports

• {}: filePath Absolute path of the file to fetch the meta data from.
• returns: {promise|*|Q.promise}

Retrieve meta information by pointing directly to the .qext file.

[stefanwalther]

I think the template isn't the problem and also your other suggestions, it's really just the pure output which doesn't really match the documentation ;-)

[jonschlinkert]

yeah the parser is going to return something unexpected when it gets something unexpected ;-)

The comments in this project are a really good example of the ideal format expected

[stefanwalther]

Hi, any plans also to support "other formats"?

[jonschlinkert]

maybe, I've never seen this format used before: {{fromFolder: Function, fromFile: Function}}, is there a convention you want me to add support for?