WordPress.org

Make WordPress Core

Opened 7 years ago

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

Download all attachments as: .zip

Change History (21)

@duck_
7 years ago

Alot of @since unkown

@duck_
7 years ago

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

Nevermind, I was missing the point.

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

Fix some doc tags

#7 @nacin
7 years ago

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

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

Related: #14953 (missing PHP Docs)

@sivel
7 years ago

phpdoc for wp-admin/includes/file.php

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

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

#12 @nacin
7 years ago

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

#13 @ryan
7 years ago

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

@itsananderson
6 years ago

Make opening bold tag a closing bold tag

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

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