[DX][Docs] Update the API documentation to include the new 'info' type for messages

[klonos]

...this is a follow-up to #3155

As it is currently, our documentation only mentions the 3 other types:

string $type: (optional) The message's type. Defaults to 'status'. These values are supported:

• 'status'
• 'warning'
• 'error'

---

PR by @klonos (informal tone): backdrop/backdrop#2317
PR by @klonos (formal tone): backdrop/backdrop#2575

[klonos]

...I went with the definitions from #3155 (comment) and a slightly informal tone in the description of each type and when is should be used. Let me now if that is not the tone we are aiming for in the API docs.

[opi]

added "need work" because you duplicate the $message part.

keeping "need review" because I'm not sure about informal tone.

[klonos]

Thanks for the review @opi 👍 ...fixed the duplicate bit.

Sure, lets wait for more feedback re tone.

[ghost]

I just came across the API docs for this and recalled seeing a fourth type in the issue queue, but still have old docs... Be good to get this updated ASAP.

As for the wording, I looked over the PR and I don't like the informal tone I'm afraid. I think I'd prefer to see the 'sophisticated' tone from the linked comment above.

[klonos]

I have created an alternative PR, which uses a formal tone: backdrop/backdrop#2575

@jenlampton your words are better than mine 😅 ...care to have a look please?

PS: I hope that nobody minds my "authoritarian" setting of the milestone. The intention is for this to not be forgotten for yet another release.

[jenlampton]

I like the PR! One recommended change:

This type is to be used when the message is not a warning nor an error. should maybe be This type is to be used when the message is not an error, a warning, or a success message. Just so we get success in there too :)

PS: I hope that nobody minds my "authoritarian" setting of the milestone.

I agree with the milestone of 1.12.6 :D

[klonos]

Thanks @jenlampton 👍 ...done.

I am assuming that we are going with the PR with the formal tone. Right?

[jenlampton]

I preferred that one :)

[quicksketch]

Merged backdrop/backdrop#2575 into 1.x and 1.12.x. Thanks folks!