SitePoint Sponsor

User Tag List

Results 1 to 14 of 14

Hybrid View

  1. #1
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Document my code: a few questions

    Hello,

    I'm in the process of documenting my code. Here are a few questions I have. Tell me if I'm doing it right or wrong:

    1.
    A param can be either a string, an integer or a boolean:
    @param{(String|Integer|Boolean)} myParam

    2.
    A method returns "this" (the "MyObject" itself)
    @return {MyObject.Instance}

    3.
    A boolean param is optional
    @param {Boolean} (optional)

    4.
    A param is either the window object, window.document or an HTMLDocument
    @param {Object|HTMLElement} myParam

    5.
    A param is a function
    @param {Function} myParam

    6.
    If a param is optional, how to specifiy its default value?
    @param {Boolean} (optional) Default is true

    7. If I make a reference to another method of an object, how to do it properly?
    @see otherMethod
    (should there be brackets? Should the method be prefixed by the Object name?)

    8. If an integer is returned, should I rather say it's a number?
    @return {Number}
    vs.
    @return {Integer}

    All the best.

    -jj.

  2. #2
    SitePoint Mentor bronze trophy
    John_Betong's Avatar
    Join Date
    Aug 2005
    Location
    City of Angels
    Posts
    1,889
    Mentioned
    74 Post(s)
    Tagged
    6 Thread(s)
    I prefer to document functions, etc with a "blackbox" approach so there is no need to delve into the function to see what it is doing.


    PHP Code:

    # MyModel Class function list
    #   public function get_customer($iStart=0, iEnd=10, & aByRef=array())
    #   public function set_customer($idCust=0, $aValues=array())


    /* #########################################
    #
    #  usage:
    #         $this->MyModel->get_customers()
    #         $this->MyModel->get_customers(22,15)
    #         $this->MyModel->get_customers(5,10, $aByRef)
    #  
    #  result:
    #         number of customer found
    #
    #  returnByRef:
    #         aByRef=array() # if and only if parameter passed
    #          
    ########################################### */
    public function get_customers($iStart=0iEnd=10, & $aByRef=array())
    {
      
    $result=0# default

      # reams of optimised code goes here

      
    return $result;

    Last edited by John_Betong; Mar 8, 2013 at 07:50. Reason: speling: not my fortay
    Learn how to be ready for The New Move to Discourse

    How to make Make Money Now with a *NEW* look

    Be sure to congratulate Wolfshade on earning Member of the Month for August 2014

  3. #3
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    Quote Originally Posted by jjshell View Post
    Tell me if I'm doing it right or wrong:
    Whether you're going it right or wrong very much depends on what generator you're coding against. When we use these doc comments, we usually intend for some program to read those comments and automatically generate documentation for us. Today, I believe the most popular tool for PHP is phpDocumentor, and you can look up their documentation for the param tag.

    EDIT: Oops, I'm not in the PHP forum, so phpDocumentor is probably not what you want. Though, the same principle holds, that whether you're doing it right or wrong depends on which generator you're coding for. Perhaps you're coding for the Closure Compiler?
    "First make it work. Then make it better."

  4. #4
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Thanks for your input.

    Yep, coding for Closure. And back to my original question

  5. #5
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    #1 seems correct, though the parentheses are unnecessary. For #2, I don't see anything in the documentation. You'll probably have to use the param's description. For #3, the Closure-specific documentation says optional arguments are marked with an equal sign {Boolean=}. However, the generic JSDoc Toolkit documentation says optional arguments are are marked with square brackets @param {Type} [varname] Description. Which of those two styles you use depends on which one works when you try generating the documentation. For #4, "Object" is neither the window nor the document. For #5, the documentation says functions are annotated as {function(string, boolean)}. For #6, the Closure-specific documentation doesn't cover this case, but the generic JSDoc documentation says @param {Type} [varname="defaultValue"] Description. For #7, the Closure-specific documentation doesn't cover this case, but the generic JSDoc documentation says @see ClassName#methodName. For #8, JS doesn't have an integer type, so number is correct.
    "First make it work. Then make it better."

  6. #6
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Awesome!!!! +1

    Thank you so much.

    For #4, how would I describe a type of window and document? {Window}? and {Document} for document? and {HTMLElement} for, well, an HtmlElement?

  7. #7
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    Quote Originally Posted by jjshell View Post
    For #4, how would I describe a type of window and document? {Window}? and {Document} for document? and {HTMLElement} for, well, an HtmlElement?
    Yup.
    "First make it work. Then make it better."

  8. #8
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Yay

    WHat type would be the event object? {Object}?

  9. #9
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    Quote Originally Posted by jjshell View Post
    WHat type would be the event object? {Object}?
    {Event}
    "First make it work. Then make it better."

  10. #10
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    One more question: what if I pass the window object (or the event object) to a function, would it be better to write:

    @param {function({Window})} / @param {function({Event})}

    or

    @param {function(window)} / @param {function(event)}


  11. #11
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    A big +1 ot you, Jeff.


  12. #12
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    With the capital letters. Because you're not defining the concrete object that ultimately gets passed. Rather, you're defining the param's type. The type means the param may be any object that implements the Window interface or the Event interface.
    "First make it work. Then make it better."

  13. #13
    SitePoint Wizard
    Join Date
    Jan 2005
    Location
    blahblahblah
    Posts
    1,447
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Capital letter and brackets?

  14. #14
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,314
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    Based on the example in the closure docs, it would seem to be without brackets.
    "First make it work. Then make it better."


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •