{"id":1452,"date":"2018-01-19T19:22:51","date_gmt":"2018-01-19T19:22:51","guid":{"rendered":"http:\/\/goofy-trucks.flywheelsites.com\/how-to-document-your-php-classes-page-4\/"},"modified":"2018-01-19T19:24:48","modified_gmt":"2018-01-19T19:24:48","slug":"how-to-document-your-php-classes-page-4","status":"publish","type":"post","link":"https:\/\/phpbuilder.com\/how-to-document-your-php-classes-page-4\/","title":{"rendered":"How To Document Your PHP Classes Page 4"},"content":{"rendered":"
\n
\n
By Stefano Locati<\/div>\n
on August 25, 2000<\/div>\n<\/p><\/div>\n
\n

Documenting Functions or Methods<\/h2>\n
\nMember functions or methods are documented with the @function<\/code> tag.<\/div>\n
\n
\n\/*! @function getItemingroup\n    @abstract gets a bagitem of a given group and a given position \n    @param groupno int - the delivery group ordinal position in the bag\n    @param pos     int - the position of the bagitem within the group \n    @result Object - the BagItem in a given position of given group\n\tor -1 if it could not be found\n *\/\n<\/pre>\n<\/div>\n
\n\"Documentation<\/div>\n
Documentation of a method.<\/i><\/div>\n
\nA @function<\/code> tag declares a function and is followed by a function or a member
\nfunction name. Then you can use @abstract<\/code> and @discussion<\/code>
\ntags like before. There are however two additional tags. The @param<\/code> tag is used to
\ndescribe function’s parameters; the first word is assumed to be the variable name, while the rest is a free text
\ndescription. I suggest to state the expected type of the variable, even if PHP is not a strong typed language.
\n The @result<\/code> tag is used to describe the return value.<\/div>\n
Documenting Variables<\/h2>\n
\nVariables or class variables are described with the @var<\/code> tag. Within this tag,
\nthe first word is assumed to be the variable’s name, while the rest is free text description. Like before
\nI suggest that writing the expected type of the variable is good. It’s also a good idea to document all
\nyour class variables.<\/div>\n
\n\"documentation<\/p>\n<\/div>\n
\nDocumentation of a class variable.<\/i><\/div>\n
\n
\n\/*! @var idsession   string - an unique session identifier *\/\nvar $idsession;\n<\/pre>\n<\/div>\n
A Final Touch<\/h2>\n
\n
\n\/*! @header myprojectname\n    @abstract a virtual store to shop on mars\n    @discussion The difference [...]\n *\/\n<\/pre>\n<\/div>\n
\nThe @header<\/code> tag is used to provide some general info about the project or the
\ngroup of classes being documented. The @header<\/code> tag itself is followed by the project name and
\nis useful to complement it with @abstract<\/code> and @discussion<\/code>
\ntags. Since classes are generally in different files (and it is usually a good idea to have one file per class named
\nafter the class name), you might wonder where you should place the @header<\/code> tag. The answer is,
\nsurprisingly enough, anywhere. I suggest to place it in a separate file if it’s a long discussion or on the
\ntop of the most important class if it’s a shorter comment.<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
By Stefano Locati on August 25, 2000 Documenting Functions or Methods Member functions or methods are documented with the @function tag. \/*! @function getItemingroup @abstract gets a bagitem of a given group and a given position @param groupno int – the delivery group ordinal position in the bag @param pos… <\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-1452","post","type-post","status-publish","format-standard","hentry","category-tutorials"],"_links":{"self":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1452","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/comments?post=1452"}],"version-history":[{"count":1,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1452\/revisions"}],"predecessor-version":[{"id":2241,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1452\/revisions\/2241"}],"wp:attachment":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/media?parent=1452"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/categories?post=1452"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/tags?post=1452"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}