Bug Report #1065

phpDoc syntax not obeyed

Added by Nowaker - about 3 years ago. Updated almost 2 years ago.

Status:Closed Start date:
Priority:Low Due date:
Assignee:Sam de Freyssinet % Done:

0%
Category:Libraries
Target version:2.4.1
Resolution:invalid Points:

Description

phpDoc helps very much while writing the code in good IDEs. So why don't you use it everywhere? Some libraries are well written, but some are not.

http://dev.kohanaphp.com/changeset/3912

Bad:

// Database object 
protected $db;

Good:

/**
* Database object
* @var Database
 */
protected $db

Kohana 2.3 libraries/Calendar.php:

     * @return  object
     */
    public static function factory($month = NULL, $year = NULL)
    {
        return new Calendar($month, $year);
    }


     * @return  object  Calendar_Event
     */
    public function event($name = NULL)
    {
        return new Calendar_Event($this);
    }

@return object - very funny...

All public methods should have @return specified (correctly), all public variables should have @var specified (correctly too).

The libraries which have @return object: Calendar, Calendar_Event, Captcha, Database, Event_Subject, Input, Image, Pagination, URI, Validation, View.

In my opinion, @return tag is the most important tag of phpDoc. I consider this critical.

Related issues

related to Kohana v2.x - Bug Report #1581: CodingStyle on Wiki should include Documentation style 2.4 Assigned 04/30/2009

History

#1
Updated by ali - about 3 years ago

Nowaker is right, it's very annoying.
I always have to edit Kohana libraries to correct @return in order to code efficiently.

#2
Updated by Woody Gilk about 3 years ago

Personally, I find the @var syntax totally obnoxious. Then again, I don't use an IDE. If you really want this fixed, I recommend providing a patch or several.

#3
Updated by Nowaker - about 3 years ago

I can provide a patch but tell me what do I have to take as a base - 2.3 release or SVN?

#4
Updated by John Heathco about 3 years ago

Use trunk SVN head... a patch would be great for this and much appreciated - I agree this should be done (and as soon as possible - I work in an IDE as well).

#5
Updated by John Heathco about 3 years ago

I think the _IDE_Helper.php file some have proposed (which declares empty class files extending the _Core classes) may be a good addition to the repository as well.

#6
Updated by Ben Rogers about 3 years ago

i disagree about the _IDE_Helper.php file, as thats something that only targets a few people, the phpDoc blocks can target everyone(even if they are not using an IDE, it maintains readability, and you can plug it into an application like phpdocumentor)

#7
Updated by John Heathco about 3 years ago

Agreed, this can be supplied in the forums. Please let me know the progress of a patch for this.

#8
Updated by Sam de Freyssinet almost 3 years ago

I personally think this ticket should be in the 2.4 milestone. It is a large task that is beyond the scope of a minor code base revision. I totally agree it should be done though.

#9
Updated by John Heathco almost 3 years ago

I agree. The hope was that a Kohana user (or users) would contribute a patch necessary for this so the developers can concentrate on bug fixes and improvements.

#10
Updated by Jeremy Bush over 2 years ago

  • Assignee set to Sam de Freyssinet
  • Priority changed from Urgent to Low
  • 11 set to 2.3.4

#11
Updated by Jeremy Bush over 2 years ago

  • Status changed from New to Review

#12
Updated by Ben Rogers over 2 years ago

maybe we can solicit on the forums for a patch to this ticket? It sounds like everyone wants to see this, but the devs are to busy...

#13
Updated by Isaiah DeRose-Wilson about 2 years ago

  • Target version changed from 2.4 to 2.4.1

#14
Updated by Isaiah DeRose-Wilson almost 2 years ago

  • Status changed from Review to Closed
  • Resolution set to invalid

These are being fixed as we update the docs. I'm going to close this issue, and if there is additional work that needs to be done we can create a new issue.

Also available in: Atom PDF