doc: remove ineffective inline code blocks

[brackendawson]

Summary

Godoc does not have inline code blocks. Look to the standard library for conventions for inline references to code.

Changes

• Replace inline code blocks in docs (uses backticks) with formats following the conventions of the standard library.

Motivation

Go doc does not have inline code blocks and backticks are unusual quotes for human readable documentation.

Related issues

Closes #1713

[brackendawson]

I discovered #1712 while making this change. I also noticed that suite.Suite.Assert() probably isn't necessary, you can just do:

func (s *MySuite) TestIfy() {
    s.Assertsions.True(true)
}

You can't travel far in testify without tripping over strange functions.

[dolmen]

@brackendawson I would prefer that we split commits based on the {assert,require}/mock/suite package groups. Because it gives more relevant Git history. Of course this is a general rule that deserves exceptions.

In this case, the change in suite are a (good) reword of some doc, not the quotes change like elsewhere, so that would deserves being its own commit, or even its own PR.

[brackendawson]

@dolmen I've split apart the formatting changes from the language changes. This PR now only converts the invalid inline code blocks to real code block and makes the code blocks into valid go. The incorrect language in the text of the comment is unchanged. I will follow up this PR with this commit to fix the language: brackendawson@0f95960

[dolmen]

@brackendawson What about my comments about adding godoc links?

[brackendawson]

@dolmen I'm not seeing any reference to godoc links? They wouldn't be relevant to this PR.

[ccoVeille]

Please use this to add a go doc link

Suggested change

	// All assertion functions take, as the first argument, the *testing.T object provided by the
	// All assertion functions take, as the first argument, the [*testing.T] object provided by the

[brackendawson]

This is a valid change so I'll make it, but I've already had to remove changes from this PR for being out of scope of of the aim of removing inline code blocks.🤨

[ccoVeille]

…

I tend to request changes that seems to be obvious when they are part of the code that is updated.

Every people is different, luckily. But I can understand it doesn't help to make a PR validated.

But from my perspectives, based on the huge amont of opened PR and the huge delay in merging the old ones, we shouldn't expect people to open a PR for a small change such as updating a comment because "well, that would be better"

I would only expect this from a very clean repository, with a very reactive team who didn't let PR open for half a decade.

Some may argue it goes against the quality standard. For me, the repository is in such terrible state that arguing about this would be a bad move.

You and I are now maintainers. We can make things better.

I went way further than I expected in this comment, but sometimes things has to be said.

[ccoVeille]

Let's merge and move forward...