1
wishcraft
Commenting is appauling 6633 Errors - Please fix immediately!

You may be aware of PHPUnit part of PEAR, there is also another package called phpDocumentor, which forms a description document for the PHP you are working on.

I have just run it on Xortify and I have around 6000 errors by the core developers in malformed or missing commenting.

When commenting the top of the file is something like:

/**
 * XOOPS Authentification base class
 *
 * You may not change or alter any portion of this comment or credits
 * of supporting developers from this source code or any supporting source code
 * which is considered copyrighted (c) material of the original comment or credit authors.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * @copyright       Chronolabs Coopertive (Australia)  http://web.labs.coop
 * @license         GNU GPL 2 (http://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
 * @package         kernel
 * @subpackage      auth
 * @since           2.0
 * @author          Pierre-Eric MENUET <pemphp@free.fr>
 * @version         $Id: auth.php 8066 2011-11-06 05:09:33Z beckmi $
 */


At the top of a class it has to contain a summary like so (the summary is the first lines with no @ ie 'Authentification base class'):
/** 
 * Authentification base class
 *
 * @package kernel
 * @subpackage auth
 * @description Authentification base class
 * @author Pierre-Eric MENUET <pemphp@free.fr>
 * @copyright copyright (c) 2000-2003 XOOPS.org
 */


All Variables have to be done like so:
/**
     * Database Property
     */
    
var $_dao;


ANd functions like propertys like variables in classes and functions are commented like so:

/**
     * Authentication of a User
     *
     * @abstract need to be write in the dervied class
     */
    
function authenticate()
    {
        
$authenticated false;

        return 
$authenticated;
    }


This file i have used as and example is fixing the issues surrounding running phpDocumentor (which is what they built the original PHP.NET sites from) on the file htdocs/class/auth/auth.php

If you would and I hope fix this issues so I don't as I do now have to go through and fix all the commenting so i have clean PHPDocuments.. I have left a copy of the dismal 8000 commenting errors copy here for a guide of where and what comments need to be fixedhttp://devl.labs.coop/2.6.0%20a3/
Resized Image
www.ohloh.net/accounts/226400

Follow, Like & Read:-

twitter.com/RegaltyFamily
github.com/Chronolabs-Cooperative
facebook.com/DrAntonyRoberts

2
Mamba
Re: Commenting is appauling 6633 Errors - Please fix immediately!
  • 2013/7/15 23:50

  • Mamba

  • Moderator

  • Posts: 11366

  • Since: 2004/4/23


Simon, the API documentation is at:
http://api.xoops.org/
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

Login

Who's Online

237 user(s) are online (124 user(s) are browsing Support Forums)


Members: 0


Guests: 237


more...

Donat-O-Meter

Stats
Goal: $100.00
Due Date: Mar 31
Gross Amount: $0.00
Net Balance: $0.00
Left to go: $100.00
Make donations with PayPal!

Latest GitHub Commits