Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation highlighting #1475

Closed
RunDevelopment opened this issue Jul 11, 2018 · 4 comments · Fixed by #2340
Closed

Documentation highlighting #1475

RunDevelopment opened this issue Jul 11, 2018 · 4 comments · Fixed by #2340

Comments

@RunDevelopment
Copy link
Member

RunDevelopment commented Jul 11, 2018

Many languages have an (at least somewhat) standardized syntax for code documentation like JavaDoc, JSDoc , PHPDoc , .Net XML doc (for C#, F# and VB.Net) and others.

Similar to most IDEs, the inline documentation comment should be displayed in a different color than normal comments. Also keywords, type and parameter references, examples and similar should be highlighted.

This means that every the themes will have to be changed to reflect the new syntax highlighting.
I am no designer, so it would be great to get some help.

Because the documentation of many languages is inspired by JavaDoc, it should not be too hard to write an abstract base of doc comment highlighting which is then extended by different languages.

Examples

PrismJS
image

GitHub

/**
 * Trims a given string.
 * 
 * @param {string} [str=""] the string.
 * @returns {string} something.
 * @throws {TypeError} if the argument is not a string.
 * @example trim(" hello ")
 */
function trim(str = "") {
	if (typeof str !== "string")
		throw new TypeError("str has to be a string");
	return str.trim();
}

Notepad++
image

VS Code
image

@mAAdhaTTah
Copy link
Member

I could see this being provided as an additional language; maybe a "language" that enhances existing languages?

@RunDevelopment
Copy link
Member Author

I originally imagined this as an extension of existing languages, but making them into their languages might be better idea.
Like this we could also support wildly different styles, which might be necessary if we ever wanted to support a language where there is no one dominating standard.

Using this approach we could do it like this:

// Prism.languages.java
'doc-comment': {
    pattern: /\/\*\*[\s\S]*?\*\//,
    greedy: true
},
...

Something like Prism.languages.javadoc would then add itself as inside.

@mAAdhaTTah
Copy link
Member

Yeah, my thought is we could have a single docblock language (or whathaveyou) that modifies all of the languages that can use JavaDoc-style documentation.

@RunDevelopment
Copy link
Member Author

RunDevelopment commented Jul 11, 2018

My idea is to make a base language javadoclike (similar to clike) and derive different languages from there.
The base language (e.g. javadoclike) will add itself to supported languages (e.g. Java) and its derived languages (e.g. javadoc) will overwrite it.

Like this, both the user and the language creators have a little more freedom.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants