Document stand-alone functions #25

Open
Couto opened this Issue May 16, 2012 · 44 comments

Comments

Projects
None yet
@Couto

Couto commented May 16, 2012

This is probably a simple question

Taking an AMD approach, how do you properly document a stand-alone function?
I've been looking at the docs and examples, but I wasn't able to find anything related…

Example to help clarify my problem:

/**
 * bind
 *
 * @version 0.0.1
 * @module function
 */
define(function () {

    /**
     * binds a function to a given object (context)
     *
     * @function
     * @param {Function} fn Function to be bound
     * @param {Object} context Object that will serve as context
     * @return {Function} bound function
     */
    return function (fn, context) { /* code */ }

});

This is an AMD module that returns a simple bind function, but because it's not a class and it's not exactly a constructor, i totally fail to make that function's documentation appear in the generated docs, at least correctly.

@davglass

This comment has been minimized.

Show comment
Hide comment
@davglass

davglass May 16, 2012

Member

Usually I just document it as a class without using the constructor tag.

Let me look into this tomorrow & see if I can make it easier.

Member

davglass commented May 16, 2012

Usually I just document it as a class without using the constructor tag.

Let me look into this tomorrow & see if I can make it easier.

@ghost ghost assigned davglass May 16, 2012

@Couto

This comment has been minimized.

Show comment
Hide comment
@Couto

Couto May 16, 2012

I'm not in a hurry so take your time =)

Personally, I wouldn't use the class tag, as I believe it can lead to misunderstanding and distracted devs might end up using the new keyword, but that's just my two cents =)

Couto commented May 16, 2012

I'm not in a hurry so take your time =)

Personally, I wouldn't use the class tag, as I believe it can lead to misunderstanding and distracted devs might end up using the new keyword, but that's just my two cents =)

@davglass

This comment has been minimized.

Show comment
Hide comment
@davglass

davglass May 16, 2012

Member

Agreed, let me see how to property do that. I think our Y.io labels itself as a static class with methods. But I agree, it's confusing. Maybe I could make it not look like a class if the static property is set.

Member

davglass commented May 16, 2012

Agreed, let me see how to property do that. I think our Y.io labels itself as a static class with methods. But I agree, it's confusing. Maybe I could make it not look like a class if the static property is set.

@Couto

This comment has been minimized.

Show comment
Hide comment
@Couto

Couto May 16, 2012

I have no idea about your police for creating new tags, but personally I feel that a function tag that accepts param and returns tags would be perfect, resulting in a module that provides functions instead of/and classes, but again, I'm just now learning in depth this world of documenting code =)

Couto commented May 16, 2012

I have no idea about your police for creating new tags, but personally I feel that a function tag that accepts param and returns tags would be perfect, resulting in a module that provides functions instead of/and classes, but again, I'm just now learning in depth this world of documenting code =)

@nym

This comment has been minimized.

Show comment
Hide comment
@nym

nym Aug 1, 2012

I'm having a similar issue- we have a ton of functions that aren't technically methods of an existing class. I could of course namespace them out, but I'd prefer not to (to reduce risk).

@spadgos of the Sublime JSDocs plugin is trying to help me here:
spadgos/sublime-jsdocs#63

nym commented Aug 1, 2012

I'm having a similar issue- we have a ton of functions that aren't technically methods of an existing class. I could of course namespace them out, but I'd prefer not to (to reduce risk).

@spadgos of the Sublime JSDocs plugin is trying to help me here:
spadgos/sublime-jsdocs#63

@mattvagni

This comment has been minimized.

Show comment
Hide comment
@mattvagni

mattvagni Nov 20, 2012

Any updates on this?

Any updates on this?

@jayarjo

This comment has been minimized.

Show comment
Hide comment
@jayarjo

jayarjo Dec 12, 2012

Having ability to document separate functions could be very helpful. We got plenty of utility functions for example (Utils).

jayarjo commented Dec 12, 2012

Having ability to document separate functions could be very helpful. We got plenty of utility functions for example (Utils).

@amatiasq

This comment has been minimized.

Show comment
Hide comment
@amatiasq

amatiasq Jun 4, 2013

Having same issue here, any update?

amatiasq commented Jun 4, 2013

Having same issue here, any update?

@manast

This comment has been minimized.

Show comment
Hide comment
@manast

manast Jul 26, 2013

Definitively a needed functionality... +1

manast commented Jul 26, 2013

Definitively a needed functionality... +1

@qraynaud

This comment has been minimized.

Show comment
Hide comment
@qraynaud

qraynaud Sep 30, 2013

Same here.

Same here.

@alcidesqueiroz

This comment has been minimized.

Show comment
Hide comment
@sergicolladosopra

This comment has been minimized.

Show comment
Hide comment
@sethyuan

This comment has been minimized.

Show comment
Hide comment

+1

@ram64

This comment has been minimized.

Show comment
Hide comment
@ram64

ram64 Nov 25, 2013

+1
In need of this functionality too.

ram64 commented Nov 25, 2013

+1
In need of this functionality too.

@caridy

This comment has been minimized.

Show comment
Hide comment
@caridy

caridy Nov 25, 2013

Member

now that we support ES6 modules to be transpiled into yui modules, and those modules can export/return a default function, we will be adding this functionally. no ETA at the moment, but it is coming.

Member

caridy commented Nov 25, 2013

now that we support ES6 modules to be transpiled into yui modules, and those modules can export/return a default function, we will be adding this functionally. no ETA at the moment, but it is coming.

@ghost ghost assigned caridy Nov 25, 2013

@plamut

This comment has been minimized.

Show comment
Hide comment
@plamut

plamut Jun 18, 2014

Any updates on this? Thanks!

plamut commented Jun 18, 2014

Any updates on this? Thanks!

@etoxin

This comment has been minimized.

Show comment
Hide comment
@etoxin

etoxin Jun 25, 2014

+1 on the update of this feature.

etoxin commented Jun 25, 2014

+1 on the update of this feature.

@dcourtois

This comment has been minimized.

Show comment
Hide comment
@dcourtois

dcourtois Jul 3, 2014

+1 documenting AMD modules can be really frustrating as is :) (the same problem happens with properties)

+1 documenting AMD modules can be really frustrating as is :) (the same problem happens with properties)

@estebanav

This comment has been minimized.

Show comment
Hide comment

+1

@benlesh

This comment has been minimized.

Show comment
Hide comment
@benlesh

benlesh Jul 23, 2014

Similar issue:

/**
* This is module that isn't a class, but is just a function, but I have all of this
* extra junk in here to describe it. OMG, what's happening?
* @module frobinate
* @class frobinate
* @method frobinate
* @param frob {Object} the frob to frobinate!
*/
export default function frobinate(frob) {
  // stuff here
};

I'm really not sure how to handle this, honestly.

benlesh commented Jul 23, 2014

Similar issue:

/**
* This is module that isn't a class, but is just a function, but I have all of this
* extra junk in here to describe it. OMG, what's happening?
* @module frobinate
* @class frobinate
* @method frobinate
* @param frob {Object} the frob to frobinate!
*/
export default function frobinate(frob) {
  // stuff here
};

I'm really not sure how to handle this, honestly.

@benlesh

This comment has been minimized.

Show comment
Hide comment
@benlesh

benlesh Jul 23, 2014

... which is really no different than

/**
* This is module that isn't a class, but is just a function, but I have all of this
* extra junk in here to describe it. OMG, what's happening?
* @module frobinate
* @class frobinate
* @method frobinate
* @param frob {Object} the frob to frobinate!
*/
module.exports = function frobinate(frob) {
  // stuff here
};

benlesh commented Jul 23, 2014

... which is really no different than

/**
* This is module that isn't a class, but is just a function, but I have all of this
* extra junk in here to describe it. OMG, what's happening?
* @module frobinate
* @class frobinate
* @method frobinate
* @param frob {Object} the frob to frobinate!
*/
module.exports = function frobinate(frob) {
  // stuff here
};
@dwelle

This comment has been minimized.

Show comment
Hide comment

dwelle commented Aug 1, 2014

+1

@lonce

This comment has been minimized.

Show comment
Hide comment

lonce commented Aug 3, 2014

+1!

@caridy

This comment has been minimized.

Show comment
Hide comment
@caridy

caridy Aug 4, 2014

Member

@blesh that's covered by the current concept of module.

yes, this is coming, I just don't have the time these days, any brave volunteer?

Member

caridy commented Aug 4, 2014

@blesh that's covered by the current concept of module.

yes, this is coming, I just don't have the time these days, any brave volunteer?

@JosefMor

This comment has been minimized.

Show comment
Hide comment
@JosefMor

JosefMor Aug 27, 2014

For "standalone functions" we use tag @for
First we define minimal one "class" as logical part of the module without any code in separated file.
After it all standalone functions, documented as methods, belongs to this logical part has @for tag.
Advantage of this solution is, that on one generated page with this "class" are all functions, belongs to it.

For "standalone functions" we use tag @for
First we define minimal one "class" as logical part of the module without any code in separated file.
After it all standalone functions, documented as methods, belongs to this logical part has @for tag.
Advantage of this solution is, that on one generated page with this "class" are all functions, belongs to it.

@barmalei

This comment has been minimized.

Show comment
Hide comment
@barmalei

barmalei Feb 23, 2015

+100

Actually I have extended yuidoc 3.xx with special tag "@api" that did the work, but lost the changes somewhere in the past. Would be great if you extend, at last, the tool with a possibility to describe just a method with no class behind. Thanks in advance.

+100

Actually I have extended yuidoc 3.xx with special tag "@api" that did the work, but lost the changes somewhere in the past. Would be great if you extend, at last, the tool with a possibility to describe just a method with no class behind. Thanks in advance.

@raphapassini

This comment has been minimized.

Show comment
Hide comment
@raphapassini

raphapassini Mar 6, 2015

I'm facing the same issue right now. I would like to have an "official" solution!
+1

I'm facing the same issue right now. I would like to have an "official" solution!
+1

@okuryu

This comment has been minimized.

Show comment
Hide comment
@okuryu

okuryu Mar 9, 2015

Member

Hi All,

You know @caridy have been very busy for other stuffs, so I'd love to work for this now.

Many people are trying to write JavaScript in ES6 (ES2015) modules now. I think making more affinity for modules is worth going, but I don't have concrete approach yet. If you have any feedback, please feel free to write to me.

Member

okuryu commented Mar 9, 2015

Hi All,

You know @caridy have been very busy for other stuffs, so I'd love to work for this now.

Many people are trying to write JavaScript in ES6 (ES2015) modules now. I think making more affinity for modules is worth going, but I don't have concrete approach yet. If you have any feedback, please feel free to write to me.

@okuryu okuryu assigned okuryu and unassigned caridy Mar 9, 2015

@balupton

This comment has been minimized.

Show comment
Hide comment
@balupton

balupton Sep 10, 2015

Just ran into this, with this code.

Documenting as a fictitious class as suggested here didn't work for me, updated code.

Also have a discussion in the Google Group.

Just ran into this, with this code.

Documenting as a fictitious class as suggested here didn't work for me, updated code.

Also have a discussion in the Google Group.

@pflannery

This comment has been minimized.

Show comment
Hide comment
@pflannery

pflannery Sep 11, 2015

@balupton Your comments are parsed by YUIDoc but it sounds like the template your using doesn't render this scenario.

example:

/**
Alias for setTimeout with paramaters reversed
@private
@method wait
@param {Number} delay Delay to send to setTimeout
@param {Function} fn Function to send to setTimeout
@return {Object} result of the setTimeout call
*/
function wait() {

}

example output json snippet

    "classitems": [
        {
            "file": "test.js",
            "line": 1,
            "description": "Alias for setTimeout with paramaters reversed",
            "access": "private",
            "tagname": "",
            "itemtype": "method",
            "name": "wait",
            "params": [
                {
                    "name": "delay",
                    "description": "Delay to send to setTimeout",
                    "type": "Number"
                },
                {
                    "name": "fn",
                    "description": "Function to send to setTimeout",
                    "type": "Function"
                }
            ],
            "return": {
                "description": "result of the setTimeout call",
                "type": "Object"
            },
            "class": ""
        }
    ]

It's also possible to add custom tags i.e. @BLAH test results in "blah": "test" in the meta data.

If the default template doesn't deal with this then maybe there is a custom template that can handle this scenario or via some custom attribute

@balupton Your comments are parsed by YUIDoc but it sounds like the template your using doesn't render this scenario.

example:

/**
Alias for setTimeout with paramaters reversed
@private
@method wait
@param {Number} delay Delay to send to setTimeout
@param {Function} fn Function to send to setTimeout
@return {Object} result of the setTimeout call
*/
function wait() {

}

example output json snippet

    "classitems": [
        {
            "file": "test.js",
            "line": 1,
            "description": "Alias for setTimeout with paramaters reversed",
            "access": "private",
            "tagname": "",
            "itemtype": "method",
            "name": "wait",
            "params": [
                {
                    "name": "delay",
                    "description": "Delay to send to setTimeout",
                    "type": "Number"
                },
                {
                    "name": "fn",
                    "description": "Function to send to setTimeout",
                    "type": "Function"
                }
            ],
            "return": {
                "description": "result of the setTimeout call",
                "type": "Object"
            },
            "class": ""
        }
    ]

It's also possible to add custom tags i.e. @BLAH test results in "blah": "test" in the meta data.

If the default template doesn't deal with this then maybe there is a custom template that can handle this scenario or via some custom attribute

@brianpeiris

This comment has been minimized.

Show comment
Hide comment
@brianpeiris

brianpeiris Oct 4, 2015

+1 Support for the revealing module pattern or ES6 in general would be great.

+1 Support for the revealing module pattern or ES6 in general would be great.

@Jaloko

This comment has been minimized.

Show comment
Hide comment
@Jaloko

Jaloko Oct 30, 2015

+1 for this feature. I'll have to use the class syntax for now.

Jaloko commented Oct 30, 2015

+1 for this feature. I'll have to use the class syntax for now.

@dsibiski

This comment has been minimized.

Show comment
Hide comment

+1

@jbaydar

This comment has been minimized.

Show comment
Hide comment

jbaydar commented Jan 13, 2016

+1

@kyleolsondesign

This comment has been minimized.

Show comment
Hide comment
@chopper

This comment has been minimized.

Show comment
Hide comment

chopper commented Jun 1, 2016

+1

@talhaobject90

This comment has been minimized.

Show comment
Hide comment

+1

@chopper

This comment has been minimized.

Show comment
Hide comment

chopper commented Jun 10, 2016

+1

@Ettapp

This comment has been minimized.

Show comment
Hide comment

Ettapp commented Jun 28, 2016

+1

@mister-walter

This comment has been minimized.

Show comment
Hide comment

+1

@barmalei

This comment has been minimized.

Show comment
Hide comment
@barmalei

barmalei Sep 23, 2016

Actually I have applied an approach that helps me to solve module/package level methods definition. The following assumptions have to be taken in account:

  • Don't use module at all, replace it with package.
  • Define a package as a class that is tagged with "package" access. For instance "commons.io" package can be defined with yuidoc as follow:
/**
 * <Package description>
 * @class commons.io
 * @access package
 */
  • You can consider package as a module if you want and place methods and variables there as you do it for a normal JS class.

You can try zebkit yuidoc theme to see how the idea works:
https://github.com/barmalei/yuidoc-zebkit-theme

barmalei commented Sep 23, 2016

Actually I have applied an approach that helps me to solve module/package level methods definition. The following assumptions have to be taken in account:

  • Don't use module at all, replace it with package.
  • Define a package as a class that is tagged with "package" access. For instance "commons.io" package can be defined with yuidoc as follow:
/**
 * <Package description>
 * @class commons.io
 * @access package
 */
  • You can consider package as a module if you want and place methods and variables there as you do it for a normal JS class.

You can try zebkit yuidoc theme to see how the idea works:
https://github.com/barmalei/yuidoc-zebkit-theme

@leebenson

This comment has been minimized.

Show comment
Hide comment
@leebenson

leebenson Dec 10, 2016

Apologies for contributing to +1 spam, but is there any movement on this?

It was suggested 4 years ago, and 'coming' a year later. Now that ES6 has most definitely landed and large swaths of code do away with modules/classes altogether, a @function tag would be put to good use!

Apologies for contributing to +1 spam, but is there any movement on this?

It was suggested 4 years ago, and 'coming' a year later. Now that ES6 has most definitely landed and large swaths of code do away with modules/classes altogether, a @function tag would be put to good use!

@davicitoafc

This comment has been minimized.

Show comment
Hide comment

+1

@ef4

This comment has been minimized.

Show comment
Hide comment
@ef4

ef4 Mar 21, 2018

As far as I can tell this is already fixed.

I came upon this issue because I was wondering how to do this, but then I found other working examples, like:

/**
  Shifts the coordinates of the given bounds using the provided
  x and y axis offset.

  @function shiftedBounds
  @param {Object} bounds The original bounds.
  @param {number} dx X axis offset.
  @param {number} dy Y axis offset.
  @return {Object} The newly calculated bounds.
*/
export function shiftedBounds(bounds, dx, dy) {

ef4 commented Mar 21, 2018

As far as I can tell this is already fixed.

I came upon this issue because I was wondering how to do this, but then I found other working examples, like:

/**
  Shifts the coordinates of the given bounds using the provided
  x and y axis offset.

  @function shiftedBounds
  @param {Object} bounds The original bounds.
  @param {number} dx X axis offset.
  @param {number} dy Y axis offset.
  @return {Object} The newly calculated bounds.
*/
export function shiftedBounds(bounds, dx, dy) {
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment