Improve docs for sanitize_title()

[ericlewis]

It's not immediately clear what sanitize_title() does. Adding doc modifications.

[swissspidy]

After looking at the ​PHP Documentation Standards I made some small adjustments to your patch, adding/removing newlines and backticks where necessary.

[wonderboymusic]

Sanitizes a string for use as a slug in a URL. is incomplete. Also sanitizes for use as HTML id or class attribute value. There may be other uses...

[DrewAPicture]

See comment:3 for other use cases we need to cover.

[DrewAPicture]

Still some work left here. Let's move it off the milestone until there's a consensus on the best way to document the intent vs the actual usage of these functions. I'd probably suggest going the route of describing the literal characters removed or accepted for any of these formatting functions – since they tend to get used in all sorts of contexts unrelated to the original intent.

[psdtohtmlguru]

@DrewAPicture Can i have this ticket please?

[swissspidy]

Replying to psdtohtmlguru:

@DrewAPicture Can i have this ticket please?

A ticket does not belong to anybody, so feel free to submit a patch as you like :)

[DrewAPicture]

Assigning to mark the good-first-bug as "claimed".

[SergeyBiryukov]

@psdtohtmlguru, still interested in making a patch?

[psdtohtmlguru]

@SergeyBiryukov Yes, i will submit soon.

[swissspidy]

There's a tutorial for working with patches in the handbook: ​https://make.wordpress.org/core/handbook/tutorials/working-with-patches/

After creating a patch file you can upload it here to this ticket.

[sjmur]

Interested in taking this and finishing it. What are we trying to say at this point? Not sure on the language from reading comments.

`

[gma992]

Rephrasing what sanitize_title() does

[gma992]

@wonderboymusic

Sanitizes a string for use as a slug in a URL. is incomplete. Also sanitizes for use as HTML id or class attribute value. There may be other uses...

Not sure if I'm missing something here, but basically sanitize_title() strip tags, removes accents and replace special characters, right? I'm not really sure what you mean with id or class attribute value.

[gma992]

Rephrased again, special characters are replaced too.

[shulard]

Maybe it's just that the sanitize_title function is sometimes used to generate an id or class from a string to ensure that non authorized characters are not used... Maybe useful only when generating attributes from inputed text.

Replying to gma992:

@wonderboymusic

Sanitizes a string for use as a slug in a URL. is incomplete. Also sanitizes for use as HTML id or class attribute value. There may be other uses...

Not sure if I'm missing something here, but basically sanitize_title() strip tags, removes accents and replace special characters, right? I'm not really sure what you mean with id or class attribute value.

[ebinnion]

5th attempt at solution

[ebinnion]

@tim1602 and I worked on another possible solution at contributor day at WordCamp DFW 2017.

Since some of the pushback in early patches seemed to be that we weren't handling all of the cases of sanitize_title(), for example how it's used in URLs in some cases, and attributes in others... It seemed like it might be best to stay ambiguous and then mention URLs and attributes as examples.

We also tried to expand on the long description by mentioning the sanitize_title filter and the default output.

[whyisjake]

In 48432:

Formatting: Improve the docblock for sanitize_title().

Since sanitize title is largely used for html attributes, or post slugs, make note that accents will be removed and that the string will be limited to alphanumeric characters, underscores, and dashes.

Fixes #33756.
Props ericlewis, swissspidy, wonderboymusic, psdtohtmlguru, DrewAPicture, SergeyBiryukov, sjmur, gma992, shulard, ebinnion, whyisjake.