Make WordPress Core

Opened 14 years ago

Closed 14 years ago

#14783 closed enhancement (fixed)

Incorrect/missing PHPDoc

Reported by: duck_'s profile duck_ Owned by:
Milestone: 3.1 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: ongoing-project
Focuses: Cc:

Description

Inspired by the 3.org API reference and the spit and polish nature of 3.1 this ticket is for patches addressing problems with current PHPDoc, e.g. spelling/factual corrections and writing missing docs.

Also, testing some methods for easily getting information for docs (e.g. version of introduction).

Attachments (6)

since-tags.diff (9.8 KB) - added by duck_ 14 years ago.
Alot of @since unkown
14783.001.diff (3.5 KB) - added by duck_ 14 years ago.
14783.002.diff (37.7 KB) - added by duck_ 14 years ago.
Fix some doc tags
14783.003.diff (4.9 KB) - added by sivel 14 years ago.
phpdoc for wp-admin/includes/file.php
14783.more-params.diff (10.3 KB) - added by duck_ 14 years ago.
16695.close-bold-tag.diff (712 bytes) - added by itsananderson 14 years ago.
Make opening bold tag a closing bold tag

Download all attachments as: .zip

Change History (21)

@duck_
14 years ago

Alot of @since unkown

@duck_
14 years ago

#1 follow-up: @duck_
14 years ago

Note in 14783.001.diff there is the removal of the default array() for the $postarr parameter in wp_insert_post. This strikes me (also discussed briefly with nacin) as very odd since leaving out $postarr makes wp_insert_post useless and it will always return 0.

#2 in reply to: ↑ 1 @filosofo
14 years ago

Replying to duck_:

This strikes me (also discussed briefly with nacin) as very odd since leaving out $postarr makes wp_insert_post useless and it will always return 0.

In wp-admin/includes/post.php:

543         $post_ID = wp_insert_post( $_POST );

There is no check within that function (wp_write_post()) that the $_POST array is populated.

#3 @filosofo
14 years ago

Nevermind, I was missing the point.

#4 @jacobsantos
14 years ago

The point of inline documentation and its fixes is to not introduce possible bugs. This enables them to be committed quickly and without testing.

#5 follow-up: @nacin
14 years ago

(In [15564]) phpdoc, @since, whitespace. Also require an argument in wp_insert_post(). props duck_, see #14783.

#6 in reply to: ↑ 5 @jacobsantos
14 years ago

Replying to nacin:

(In [15564]) phpdoc, @since, whitespace. Also require an argument in wp_insert_post(). props duck_, see #14783.

If that is the case, then the bug is somewhere else in the code and you are just covering up the cause.

While it is true that probably no where in the code will this function be called without passing at least something in the $postarr variable, it is made at the very least to stand as a feature for someone who wants to create a post and then fill it at some later time. There are a few cases where you'll want to fill in some data and then go back and fill in the rest once you know more.

Furthermore, this change should be in its own ticket to further track its progress and any other information that might be needed.

@duck_
14 years ago

Fix some doc tags

#7 @nacin
14 years ago

(In [15590]) Phpdoc argument/@param cleanups. props duck_, see #14783.

#8 @hakre
14 years ago

I was not aware of this ticket, those are some more PHPDoc related ones:

  • #14726 - PHPDoc @license Tag Review
  • #14921 - WP_Dependencies is tagged as external but is core package
  • #14928 - wp_mkdir_p() phpdocs do not explain the "p" in the function name in full (one documentation only patch available)

#9 @hakre
14 years ago

Related: #14953 (missing PHP Docs)

@sivel
14 years ago

phpdoc for wp-admin/includes/file.php

#10 @jane
14 years ago

  • Keywords ongoing-project added

Anyone planning to add more to this one should do so by November 1st to get in before freeze.

#11 @nacin
14 years ago

(In [16024]) Docs for wp-admin/includes/file.php. props sivel, see #14783.

#12 @nacin
14 years ago

(In [16469]) More param fixes, props duck_. see #14783.

#13 @ryan
14 years ago

  • Resolution set to fixed
  • Status changed from new to closed

@itsananderson
14 years ago

Make opening bold tag a closing bold tag

#14 @itsananderson
14 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Reopening for an additional patch. It made more sense to reopen this ticket than to create a new one.

#15 @PeteMall
14 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed
Note: See TracTickets for help on using tickets.