render-function.md — tick consistency

[MachinisteWeb]

• tick consistency to highlight code part in text comment

[chrisvfritz]

Hmm, I'm wondering if we want to go the other way and consistently remove backticks from comments. For those not familiar with markdown, they could be confusing. What are others' thoughts?

[MachinisteWeb]

Hi @chrisvfritz !

This is my throughs.

In a normal text (.txt) all you right is only ponctuation. So if you want highlight something important, one of the way is to place some « " » (in english). E. g.

/*...*/
{
  route, // the ES6 « route » property is the same as « route: route » in ES5. We recommand « ES6 » format as Bob said « ES6 is better than ES5 because 6 is after 5 ».
  data: () => {}
}
/*...*/

But this is really poor to indicate the different level of informations.

That's why for web presentation some <strong>, <samp>, <em>, <var> etc. tag was created.

But the main propose of Markdown is to « allows plain text to be readable and in same time to allows all this level of conplexity « without » use parsing to create .something from .md (e. g. .htm) necesarly.

One of capability as a result of that, is Markdown is easy to write, easy to read and easy to parse because text contains differents level of information we can find in others « language » (as in HTML).

---

I understand your problematic as following:

« Because our actual process not allows us to « parse » Markdown inside code comment (or simply because it's a plain text), maybe it is a better choice to not use Markdown ».

For exemple, JSDoc parser allows some comments to be a part of API documentation generated. Parser parse and transform Markdown into valid HTML for a webdoc (or maybe valid Word tag for a .docx doc, etc.).

So I think :

• because Markdown was create to allows more readibility to plain text, and a comment is a plain text : is a good idea to use it.
• it's not because our current tool do not allows parse Markdown that we must not used it.

So, in french documentation we use the following rules:

• if the part of text is a valid JavaScript/HTML/what-you-want code, we surrounded it with tick.
• if the part of text is a code-like syntax that's only serve as an example, we do nothing. e. g. { Array | String } (or sometime when it's clearly the API style used).

(For second if we use that because it's we have observed in majority accross all vue, vue-loader, vue-router, vue-server-renderer, vuex, etc. documentations. But ultimatly, using tick for all thing that's look like a « code » (even if it's not a valid code) is possible we think).

So the previous code could become :

/*...*/
{
  route, // the ES6 `route` property is the same as `route: route` in ES5. We recommand **ES6** format as Bob said _ES6 is better than ES5 because 6 is after 5_.
  data: () => {}
}
/*...*/

That bring more level of information than:

/*...*/
{
  route, // the ES6 route property is the same as route: route in ES5. We recommand ES6 format as Bob said ES6 is better than ES5 because 6 is after 5.
  data: () => {}
}
/*...*/

and remove some comprehension difficulty:

/*...*/
  route // same as route: route
/*...*/

« What is this curious phrase ponctuation syntax ? Oh... it's a code explaination »

---

Another point that not directly concern the english documentation:

For french, we have another point, (that's probably the same for others languages that is not in english).

If you said (speaking about a variable called children):

// Use children is more important`

Because in french the word « children » become « enfants », we prefer clearly identify what is a part of code and what is a part of plain english word because in one case we translate by

// Utiliser des enfants est plus important.

or

// Utiliser `children` est plus important.

---

That's all for me :p

[chrisvfritz]

You've convinced me. 😄 For people who don't understand Markdown yet, it could initially be confusing, but I now agree that it's not difficult to get used to the convention and that for those who can already read markdown, it will be simpler.

[MachinisteWeb]

And learn Markdown is not a big difficulty and it's a great tools that all developer should have in his/her skills to « communicate » accross plain text document, chat, email, code comment, etc. I'm proud to say : Vue provided it with code comment :P