WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

Last modified 5 years ago

#7526 closed enhancement (fixed)

Inline Documentation for wp-config-sample.php

Reported by: santosj Owned by:
Milestone: 2.7 Priority: low
Severity: minor Version:
Component: Optimization Keywords: phpdoc has-patch
Focuses: Cc:

Description

Patch converts inline documentation to phpdoc style inline documentation with link to wp-config.php codex page.

Attachments (4)

7526.phpdoc.diff (5.6 KB) - added by santosj 6 years ago.
PHPdoc for #7526 for trunk.
7526.phpdoc.r8653.diff (5.9 KB) - added by santosj 6 years ago.
Patch for wp-config-sample.php phpdoc based off of r8653
7526.phpdoc.r8665.diff (4.4 KB) - added by santosj 6 years ago.
Reduced phpdoc based off of r8665
7526.r8793.diff (3.9 KB) - added by jacobsantos 6 years ago.
Hopefully improved, shorten version of phpdoc, based off of r8793.

Download all attachments as: .zip

Change History (33)

santosj6 years ago

PHPdoc for #7526 for trunk.

comment:1 santosj6 years ago

  • Component changed from General to Optimization
  • Priority changed from normal to low
  • Severity changed from normal to minor

santosj6 years ago

Patch for wp-config-sample.php phpdoc based off of r8653

comment:2 santosj6 years ago

New patch adds link to Ryan Boren post on the new Authentication keys.

comment:3 azaozz6 years ago

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

(In [8655]) wp-config-sample.php inline documentation. Props santosj, fixes #7526

comment:4 westi6 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

While I am +1000 in general for phpdocing everything.

i think this may be a bit overboard.

We need to remember that this is the file that we encourage users to edit - hence why it has it's svn eol style set to Windows (as that is where most users will edit it).

I am -1 for this patch as it makes the file much harder for a user to use.

I would prefer a reduced phpdoc patch or just revert it all together for now.

comment:5 santosj6 years ago

Reduced PHPdoc, can you explain further what needs to be reduced? Does the phpdoc make it harder to read? Some of the phpdoc is there, for developers to know when the constant started to exist, I suppose this can be reduced.

santosj6 years ago

Reduced phpdoc based off of r8665

comment:6 santosj6 years ago

  • Keywords has-patch added

How is that patch?

comment:7 Viper007Bond6 years ago

-1 to phpdoc in wp-config-sample.php. It's designed more for a technical person than the average Joe.

We should stick to plain English.

comment:8 santosj6 years ago

Non-technical people are unlikely to create their own wp-config.php and more likely to use the wp-config.php installer.

comment:9 santosj6 years ago

  • Keywords phpdoc added

comment:10 caesarsgrunt6 years ago

I agree with westi and Viper007Bond.

PHPdoc is great in the core WP files, which will only be seen by developers. However, it really does make this file too cluttered and could easily confuse the average user.

I propose reverting [8655].

This isn't to say it should be left as it was before, just not PHPdoc or such in-depth dev-only detail.

eg instead of

/**
 * The name of the database.
 *
 * @var string
 * @since unknown
 */
define('DB_NAME', 'putyourdbnamehere');

how about

// The name of the database for WordPress
define('DB_NAME', 'putyourdbnamehere');

comment:11 Viper007Bond6 years ago

Exactly what I was thinking. Documentation is good, but 99.99% of users who see the config file won't give a rats ass the var type, since version, etc. Plus the phpdoc style just adds tons of unnecessary code and confusion to non-devs.

comment:12 ryan6 years ago

(In [8790]) Revert [8655]. see #7526

comment:13 jacobsantos6 years ago

  • Keywords needs-patch added; has-patch removed

WTF?

What is the difference between:

// The name of the database for WordPress
define('DB_NAME', 'putyourdbnamehere');

And

/** The name of the database for WordPress */
define('DB_NAME', 'putyourdbnamehere');

Answer: The phpDocumentor sites don't pick up the first one, while they do with the second one.

Riddle me this: What is the difference between these two comments?

<?php
// This file holds the configuration of WordPress.

And

<?php
/**
 * This file holds the configuration of WordPress.
 */

At the very least, the file level phpdoc should be kept.

comment:14 follow-up: ryan6 years ago

Your patch didn't apply cleanly. I'm too lazy to make it apply tonight. Tomorrow, I will be less lazy. :-)

comment:15 Viper007Bond6 years ago

/** The name of the database for WordPress */

is fine by me. It looks clean, is easy to read, but can still be parsed.

7526.phpdoc.r8665.diff is a step in the right direction, but it's still too big IMO. Stuff like SECURE_AUTH_KEY doesn't need all of that documentation. A simple explanation and a link to the Codex would be better.

comment:16 in reply to: ↑ 14 jacobsantos6 years ago

Replying to ryan:

Your patch didn't apply cleanly. I'm too lazy to make it apply tonight. Tomorrow, I will be less lazy. :-)

I can try again, this time without the extra stuff.

comment:17 caesarsgrunt6 years ago

Replying to jacobsantos:

Yes, as Viper007Bond says,

/** The name of the database for WordPress */
define('DB_NAME', 'putyourdbnamehere');

is fine by me. I didn't really mean PHPdoc syntax couldn't be used, just that the very verbose stuff which was there was bad, and that it was best on a single line.

I hadn't noticed the suggested patch by santosj, actually... (I take it jacobsantos and santosj are one and the same person?)

comment:18 follow-up: jacobsantos6 years ago

Yes, santosj is my other handle. Internet etiquette dictates that you should only have one handle, but well, I forgot my password and I'll send it to myself so I only have one.

jacobsantos6 years ago

Hopefully improved, shorten version of phpdoc, based off of r8793.

comment:19 follow-up: jacobsantos6 years ago

I think the /**#@+*/ and /**#@-*/ needs to be tested to ensure that all there constants get the descriptions.

comment:20 jacobsantos6 years ago

  • Keywords has-patch added; needs-patch removed

comment:21 in reply to: ↑ 18 ; follow-up: jacobsantos6 years ago

Replying to jacobsantos:

Yes, santosj is my other handle. Internet etiquette dictates that you should only have one handle, but well, I forgot my password and I'll send it to myself so I only have one.

I also try to sound smarter, than I am.

comment:22 in reply to: ↑ 19 caesarsgrunt6 years ago

The new version basically is much better than the last, but still a bit long-winded I think.

But... WTF are /**#@+*/ and /**#@-*/ ???

Perhaps #7397 could be fixed in the patch for this, too, especially since this keeps breaking and re-breaking #7397's existing patch.

comment:23 in reply to: ↑ 21 ; follow-up: caesarsgrunt6 years ago

Replying to jacobsantos:

Yes, santosj is my other handle. Internet etiquette dictates that you should only have one handle, but well, I forgot my password and I'll send it to myself so I only have one.

I also try to sound smarter, than I am.

I'm actually impressed. You mean you have different passwords for everything, like you should? :-p

comment:24 in reply to: ↑ 23 ; follow-up: jacobsantos6 years ago

Replying to caesarsgrunt:

Replying to jacobsantos:

Yes, santosj is my other handle. Internet etiquette dictates that you should only have one handle, but well, I forgot my password and I'll send it to myself so I only have one.

I also try to sound smarter, than I am.

I'm actually impressed. You mean you have different passwords for everything, like you should? :-p

No, I mean I have two usernames with different passwords that I didn't create, which both are difficult to remember. It seems you are impressed with the username / password scheme of WordPress username integration system. I am too.

I keep trying to add #7397, but the core developer team is smarter than that. I think it belongs in its own ticket, so we can debate it for another week or so, then get bored and then bring it up in another 3 or 4 months or so.

/**#@+*/ and /**#@-*/ are attempts to keep the long winded patch even less long winded. There are several converters used by phpDocumentor that will apply the phpdoc comment to every documentable element between those two. Basically, if they get the unique phrases from the web site like they should, then they will replace all of the hard work (not that it matters once it goes into wp-config.php, people shouldn't be applying phpDocumentor to their live sites anyway, because the constants' value might be picked up).

comment:25 in reply to: ↑ 24 caesarsgrunt6 years ago

Replying to jacobsantos:

I keep trying to add #7397, but the core developer team is smarter than that. I think it belongs in its own ticket, so we can debate it for another week or so, then get bored and then bring it up in another 3 or 4 months or so.

It's just that it's more 'enhancement' of the wp-config-sample.php inline documentation, which this ticket is enhancing anyway. But whatever.

/**#@+*/ and /**#@-*/ are attempts to keep the long winded patch even less long winded. There are several converters used by phpDocumentor that will apply the phpdoc comment to every documentable element between those two. Basically, if they get the unique phrases from the web site like they should, then they will replace all of the hard work (not that it matters once it goes into wp-config.php, people shouldn't be applying phpDocumentor to their live sites anyway, because the constants' value might be picked up).

Ah, clever.
In that case yes, I think 7526.r8793.diff is good - commit?

comment:26 Viper007Bond6 years ago

Patch looks good to me. Nice work.

comment:27 jacobsantos6 years ago

Can the patch be committed to see how it looks in the phpDocumentor site?

comment:28 jacobsantos6 years ago

  • Summary changed from WP-Config-Sample.php inline documentation to Inline Documentation for wp-config-sample.php

comment:29 westi6 years ago

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

(In [8817]) Improved phpdoc for wp-config-sample.php fixes #7397 and #7526 props lloydbudd and jacobsantos.

Note: See TracTickets for help on using tickets.