Comments for PHP class and functions
PHPDocumentor style is pretty standard and understood by most IDE’s and documentation generators.
/** * Photos * * * @package CI * @subpackage Controller * @author YOUR NAME */ class Photos extends CI_Controller < /** * * Uploads a file * * @param string $file_name description * @param string $new_name description * @param integer $new_width description * @param integer $new_height description * @param string $directory description * @return boolean */ public function upload($file_name, $new_name, $new_width, $new_height, $directory) < >> Read More
I would use Natural Docs. The doc comments are easy to read right in the code thanks to human-friendly formatting:
it. Arguments: file_name - name of the file new_name - name of the file on the server new_width - resize to this before uploading new_height - resize to this before uploading Returns: true or false. See Also: */ public function upload($file_name, $new_name, $new_width, new_$height, $directory)
You might want to look at Doxygen. If you follow their syntax not only will you be able to auto generate documentation (not actually so useful), but the Zend Studio IDE will give you code hints on auto completion (i.e., it will display the documentation when you start to type the function name).
/*! \brief My Photo Class * Does some stuff with photos */ class Photos extends CI_Controller < /*! \brief Uploads a file * \param $file_name The name of the file * . * \returns A value indicating success */ public function upload($file_name, $new_name, $new_width, new_$height, $directory) < . . returns true or false. >> 
satnhak 9010
/** * A sample function docblock * @global string document the fact that this function uses $_myvar * @staticvar integer $staticvar this is actually what is returned * @param string $param1 name to declare * @param string $param2 value of the name * @return integer */ function firstFunc($param1, $param2 = 'optional')
This will also be helpful for auto-complete in most known editors.
More Answer
- PHP Design pattern to pass a class name and check it for the class existence
- SQL design and / or PHP class for storing dynamic two-dimensional arrays?
- How can I create and execute a series of PHP Variable Functions in a for loop?
- PHP inherit class and use functions defined in external files
- Handling Global Variables between different Classes and Functions in PHP
- PHP Class returning values and setting variables
- regular expression for some special charaters and number in php
- php — check for endless possibility and stop when reach the end
- PHP functions and if/else statements
- Can you advise me a good continuous integration tool for PHP and tell me why?
- Vim: Good AutoCompletion Plugin for Python and PHP
- PHP Class Function List in Comments
- Getting timezone for JavaScript and PHP all mixed up
- Image compression and thumbnail creation for PHP
- javaScript fire php file and dont wait for reply
- PHP and Databases: Views, Functions and Stored Procedures performance
- Replacement or equivalent to __destruct() and unset() for PHP 7+
- Php check for specific word and change color
- What is meant by backtrace in php why we use debug_backtrace() and debug_print_backtrace() functions in php?
- Syntax error: PHP brackets issue for IF and FOREACH?
- php for this week and next
- Scan string for first occurrence of certain word and replace word plus next few characters with php
- C# and PHP show two different results for a calculation with the same code logic
- Laravel 5.1, creating global functions and creating new method for creating links from array
- Defining class name using php and regex matching in HTML
- PHP OOP use extends class in functions
- PHP Variable Functions and language constructs
- Progressbar for between 2 dates with php and css
- PHP Variables and its checking for null with some discipline
- php oop: making anonymous functions in an array inside a class
- Store and use global variables in the same class, but different public functions using php
- Absolute Path for Shared Servers and Local Servers with PHP for CSS
- how to clean POST and GET vars in PHP for XSS and SQL injection
- submitting multiple forms with one button for both php and javascript
- Looking for PHP BPMN 2.0 and service bus ‘esb’
- How to get all comments and likes for a facebook post?
- Is it possible to access and set the «File is ready for archiving» flag with PHP in Windows?
- How to get SQL-like HAVING and GROUP BY for PHP arrays?
- Is it right to send PHP and Apache version in user agent string for an API?
- What functions should I know for testing php code?
- Does PHP have functions any() and all()?
- passcode for PHP script between PHP and iPad
- PHP forward and backward for loop verse
- Where can i get AES encyrption for PHP and can AES encrytion be used for document storage?
- Keeping a same format and logging for all the errors in PHP
- can I use both php and java for a same web application
More answer with same ag
- PHP: Does using traits a lot impact performance?
- Symfony 2.7: Could not load type «Symfony\Component\Form\Extension\Core\Type\TextType»
- Understanding relative paths
- alert not showing jquery
- Number and a date range filter for datatable serverside script
- Why does my JQuery script seems to only works before beginning to browse my tabs if the content of my tabs is the same everywhere?
- Printing results from function on page onclick?
- Overwriting Kohana_Core
- Dont allow access to txt files in root via .htaccess
- How to call a bootstrap modal popup from PHP
- strings after »
- Zend Framework 2: How to use my own User table in ZfcUser
- PHP unit failure testing
- RegEx Capture Group with PHP preg_match Not Returning Values
- PHP — How to search folder images per order
- How to parse html textarea input for special variable
- how to calculate sum of column values by removing duplicate id’s using PHP in excel sheet?
- Yii framework CGridView in 3rd. party application
- javascript keep checkbox checked after refresh page
- Configuration for Lighttpd FastCGI under high traffic
- Magento «addAttributeToFilter like» with OR statement not working
- How to select JSON output into TableViewCell in Swift 3.0 ?
- How to insert new_class style on php echo?
- Serializing a JSON object to send via AJAX
- PHP curl_multi_exec is using 99% cpu . Any special apache or php configuration to lower cpu usage?
- switch condtion going on first case on int 0
- Adding an array into an array of arrays
- Reason ForceType application/x-httpd-php on .htaccess not working at all
- posting an array using JQuery .post()
- Implementation of multilanguage in PHP
- Dynamically access array in Laravel Blade
- coloring with hsl with my php code
- How to check if a value exists in AJAX success response
- I don’t know how to implement a logic in symfony
- php clickable image inside form with get resulting in x-y coordinates
- How to query the inverse side of a ManyToOne relationship?
- highlight last 3 number in the string
- setlocale() not working properly with date()
- Java array of objects with defined keys
- Is there a way to fill a textarea form with SQL data that contain linebreak from ENTER key?
- Form: Post to multiple action or one based on input?
- Javascript Redirect Mobile Specific Page
- PHP how to get substring between certain keywords
- URI from Response on GuzzleHttp
- PHP Relative Pathing
- Redirect from ALL subpages to Homepage?
- Passing tns:ArrayOfString to SOAP client
- Javascript — Uncaught TypeError: Cannot read property ‘value’ of undefined
- PHP: Interpret arguments as array?
- Multiple file upload limit
CodeSniffer File Doc Comment And Class Doc Comment
Note: This post is over two years old and so the information contained here might be out of date. If you do spot something please leave a comment and we will endeavour to correct.
Yesterday I wrote two posts about CodeSniffer and a common warning that I couldn’t find any decent documentation on. I thought that today I would go over something that I also had trouble finding out about, this is the file doc error. When you run CodeSniffer on a class you might find the following error being produced.
Most developers should be familiar with doc comments. They are used as a standard model for commenting and can also be used to generate API documentation automatically. What the CodeSniffer documentation doesn’t explain is the difference between a file doc comment and a class doc comment. A class doc comment is a comment that precedes a class, it describes not only what the class does, but also gives author, version and license information. Here is a typical (and very simple) class doc comment. The @ symbols are used to generate the API documentation.
A file doc comment is placed at the top of the file, above any include statements and contains pretty much the same information as the class doc comment. When added to your application your document structure might look like this.
As long as you make sure that different lines are spaced correctly, and that there is a single blank line between the class comment and the first parameter, you should find that running CodeSniffer will produce no errors. You will also be able to generate some pretty neat documentation which you can bundle with your application.
Phil is the founder and administrator of #! code and is an IT professional working in the North West of the UK. Graduating in 2003 from Aberystwyth University with an MSc in Computer Science Phil has previously worked as a database administrator, on an IT help desk, systems trainer, web architect, usability consultant, blogger and SEO specialist. Phil has lots of experience building and maintaining PHP websites as well as working with associated technologies like JavaScript, HTML, CSS, XML, Flex, Apache, MySQL and Linux.
Want to know more? Need some help?
Let us help! Hire us to provide training, advice, troubleshooting and more.
Support Us!
Please support us and allow us to continue writing articles.
Comments for PHP class and functions
PHPDocumentor style is pretty standard and understood by most IDE’s and documentation generators.
/** * Photos * * * @package CI * @subpackage Controller * @author YOUR NAME [email protected]> */ class Photos extends CI_Controller < /** * * Uploads a file * * @param string $file_name description * @param string $new_name description * @param integer $new_width description * @param integer $new_height description * @param string $directory description * @return boolean */ public function upload($file_name, $new_name, $new_width, $new_height, $directory) < >> Solution 2
/** * A sample function docblock * @global string document the fact that this function uses $_myvar * @staticvar integer $staticvar this is actually what is returned * @param string $param1 name to declare * @param string $param2 value of the name * @return integer */ function firstFunc($param1, $param2 = 'optional')
This will also be helpful for auto-complete in most known editors.
Related videos on Youtube
sunjie
Updated on February 02, 2022
Comments
I would like to add some documentation comments for my (PHP) class and its functions in some standard format, so that it’s easier for others to understand. What would an example of how you would write comments for the following class and function? Information about the class: Classname Photos: it has some functions related to uploading the photo and displaying the photos. Function names are upload() , display() , delete() . Information about the upload function: Uploads the resizes and uploads the image and has few parameters as shown below.
IMO the width arguments shouldnt be on that method. They are a strong indicator that your upload function does more than just uploading (e.g. it also does resizing)
If you’re going with the PHPDoc syntax, I’d recommend giving DocBlox a try. It’s PHP 5.3 compliant and much faster than phpdoc.