Inline Documentation for wp-config-sample.php

[santosj]

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

[santosj]

PHPdoc for #7526 for trunk.

[santosj]

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

[santosj]

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

[azaozz]

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

[westi]

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.

[santosj]

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.

[santosj]

Reduced phpdoc based off of r8665

[santosj]

How is that patch?

[Viper007Bond]

-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.

[santosj]

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

[caesarsgrunt]

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');

[Viper007Bond]

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.

[ryan]

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

[jacobsantos]

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.

[ryan]

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

[Viper007Bond]

/** 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.

[jacobsantos]

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.

[caesarsgrunt]

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?)

[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.

[jacobsantos]

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

[jacobsantos]

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

[jacobsantos]

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.

[caesarsgrunt]

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.

[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

[jacobsantos]

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).

[caesarsgrunt]

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?

[Viper007Bond]

Patch looks good to me. Nice work.

[jacobsantos]

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

[westi]

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