WordPress.org

Make WordPress Core

Opened 10 years ago

Closed 10 years ago

#14783 closed enhancement (fixed)

Incorrect/missing PHPDoc

Reported by: 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_ 10 years ago.
Alot of @since unkown
14783.001.diff (3.5 KB) - added by duck_ 10 years ago.
14783.002.diff (37.7 KB) - added by duck_ 10 years ago.
Fix some doc tags
14783.003.diff (4.9 KB) - added by sivel 10 years ago.
phpdoc for wp-admin/includes/file.php
14783.more-params.diff (10.3 KB) - added by duck_ 10 years ago.
16695.close-bold-tag.diff (712 bytes) - added by itsananderson 10 years ago.
Make opening bold tag a closing bold tag

Download all attachments as: .zip

Change History (21)

@duck_
10 years ago

Alot of @since unkown

@duck_
10 years ago

#1 follow-up: @duck_
10 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
10 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
10 years ago

Nevermind, I was missing the point.

#4 @jacobsantos
10 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
10 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
10 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_
10 years ago

Fix some doc tags

#7 @nacin
10 years ago

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

#8 @hakre
10 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
10 years ago

Related: #14953 (missing PHP Docs)

@sivel
10 years ago

phpdoc for wp-admin/includes/file.php

#10 @jane
10 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
10 years ago

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

#12 @nacin
10 years ago

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

#13 @ryan
10 years ago

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

@itsananderson
10 years ago

Make opening bold tag a closing bold tag

#14 @itsananderson
10 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
10 years ago

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