WordPress.org

Make WordPress Core

Opened 4 years ago

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

Download all attachments as: .zip

Change History (21)

duck_4 years ago

Alot of @since unkown

duck_4 years ago

comment:1 follow-up: duck_4 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.

comment:2 in reply to: ↑ 1 filosofo4 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.

comment:3 filosofo4 years ago

Nevermind, I was missing the point.

comment:4 jacobsantos4 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.

comment:5 follow-up: nacin4 years ago

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

comment:6 in reply to: ↑ 5 jacobsantos4 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_4 years ago

Fix some doc tags

comment:7 nacin4 years ago

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

comment:8 hakre4 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)

comment:9 hakre4 years ago

Related: #14953 (missing PHP Docs)

sivel4 years ago

phpdoc for wp-admin/includes/file.php

comment:10 jane3 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.

comment:11 nacin3 years ago

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

duck_3 years ago

comment:12 nacin3 years ago

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

comment:13 ryan3 years ago

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

itsananderson3 years ago

Make opening bold tag a closing bold tag

comment:14 itsananderson3 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.

comment:15 PeteMall3 years ago

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