Use html and/or backticks in resources properties descriptions?

[eri-trabiccolo]

This is the hamletic question afflicting me and @pondermatic on slack!

James says:

I just searched the output of /wp-json and found NO markup in descriptions. Nothing says to not use markup, but the convention seems to be not to use markup.

but we also found that no backticks are used as well.

James:

Since the schema is mostly meant to be machine readable, the description field is not usually going to be used. Developers may look at it. Maybe someone has written a tool to take the output and turn it into a HTML document, sort of like ReDoc and Swagger-UI. If so, that tool should correctly parse HTML and backticks.
I think backticks are helpful. Too much HTML can make it hard for humans to read though.

Me:

I think you’re right, the only thing is that when it’s about lists, html is useful 😄

James

True.

We both think:

we need a ruling from @thomasplevy

At the moment I used backticks somewhere and html markup somewhere else.

[thomasplevy]

Are we asking about the description field in the spec or in the actual codebase on the description props of endpoints and etc...?

In the spec I think HTML is okay, in the description on the codebase I think it would probably make sense to avoid html.

I think enclosing properties/variables in backticks in the description of the codebase is acceptable, though, if it's causing issues we can easily switch those to quotation marks.

What's "hamletic"?

[eri-trabiccolo]

Sorry, talking about description field in the actual codebase.

OK, so I will make a PR to purge description fields in the codebase from html, and use backticks.

Thanks.

[pondermatic]

hamletic

Interesting word! "undecided".
https://en.wiktionary.org/wiki/Hamletic

[eri-trabiccolo]

Oh sorry, I forgot to reply to that.
Well in Italy "hamletic" (amletico, in italian) is a pretty widespread adjective, meaning "undecided" with some tragedy in it :D
And of course refers to Shakespeare's Hamlet.

[thomasplevy]

@eri-trabiccolo sounds good. I think the priority on this is pretty low.