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

Create web-page with instructions: how to create Javadoc Check #410

Closed
baratali opened this Issue Dec 2, 2014 · 13 comments

Comments

Projects
None yet
2 participants
@baratali
Contributor

baratali commented Dec 2, 2014

baratali added a commit to baratali/checkstyle that referenced this issue Feb 17, 2016

romani added a commit that referenced this issue Feb 17, 2016

@romani romani modified the milestone: 6.16 Feb 17, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Apr 16, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Apr 16, 2016

romani added a commit that referenced this issue Apr 17, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Apr 18, 2016

Member

@baratali , please send draft notes about (they are the most critical):

  1. Javadoc is expecting XHTML , .....
  2. why why make a tree up to CHAR token ?
  3. Comment identificator for javadoc

checkstyle-6.18-all.jar , checkstyle-6.18-SNAPSHOT-all.jar

change to "checkstyle-X.XX-all.jar" we are about to become 7th and 8th version in next month or two.

Member

romani commented Apr 18, 2016

@baratali , please send draft notes about (they are the most critical):

  1. Javadoc is expecting XHTML , .....
  2. why why make a tree up to CHAR token ?
  3. Comment identificator for javadoc

checkstyle-6.18-all.jar , checkstyle-6.18-SNAPSHOT-all.jar

change to "checkstyle-X.XX-all.jar" we are about to become 7th and 8th version in next month or two.

baratali added a commit to baratali/checkstyle that referenced this issue Apr 19, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Apr 19, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Apr 20, 2016

romani added a commit that referenced this issue Apr 20, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Apr 20, 2016

Member

Check create new class and extend AbstractJavadocCheck.

all reference to class and methods should by done as links.

Overview

this paragraph should start from "What is javadoc (XHTML)" and how javadoc is detected in multiline comment.
it is the most critical point of our implementation. XHTML is so non-typicality in web, usage of it is more exception rather than a rule.

Member

romani commented Apr 20, 2016

Check create new class and extend AbstractJavadocCheck.

all reference to class and methods should by done as links.

Overview

this paragraph should start from "What is javadoc (XHTML)" and how javadoc is detected in multiline comment.
it is the most critical point of our implementation. XHTML is so non-typicality in web, usage of it is more exception rather than a rule.

@romani romani added this to the 6.18 milestone Apr 20, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Apr 26, 2016

romani added a commit that referenced this issue Apr 26, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 4, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 4, 2016

romani added a commit that referenced this issue May 5, 2016

romani added a commit that referenced this issue May 6, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani May 6, 2016

Member

@baratali

I did a lot of minor changes for documentation, please review.

We need to explain a reason why we continue parsing even javadoc content is not XHTML
We also need to use "predictable" instead of "incorrect". As "incorrect" mean bug.

We need to explain why we have in AST (CHAR, WS), as we do not have this in Java AST tree.

Please add code examples to "Access Java AST from Javadoc Check"

HTML code in Javadoc Comments

It is hard to find a difference.
Does it make sense to place them as table ? Example:

|Non-predictable| Predictable |
| javadoc | javadoc |
| AST tree | Ast tree |

Please put a link to github issue to make javadoc customizable at Overview chapter .
Please post a note to issue to update xdoc on completion.

Please make all class names and methods to be a link to javadoc.

We need to explain user what version of HTML we support . How we can support HTML5, and any further versions.

Member

romani commented May 6, 2016

@baratali

I did a lot of minor changes for documentation, please review.

We need to explain a reason why we continue parsing even javadoc content is not XHTML
We also need to use "predictable" instead of "incorrect". As "incorrect" mean bug.

We need to explain why we have in AST (CHAR, WS), as we do not have this in Java AST tree.

Please add code examples to "Access Java AST from Javadoc Check"

HTML code in Javadoc Comments

It is hard to find a difference.
Does it make sense to place them as table ? Example:

|Non-predictable| Predictable |
| javadoc | javadoc |
| AST tree | Ast tree |

Please put a link to github issue to make javadoc customizable at Overview chapter .
Please post a note to issue to update xdoc on completion.

Please make all class names and methods to be a link to javadoc.

We need to explain user what version of HTML we support . How we can support HTML5, and any further versions.

romani added a commit that referenced this issue May 6, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 10, 2016

romani added a commit that referenced this issue May 10, 2016

@baratali

This comment has been minimized.

Show comment
Hide comment
@baratali

baratali May 10, 2016

Contributor

We need to explain a reason why we continue parsing even javadoc content is not XHTML

done

We need to explain why we have in AST (CHAR, WS), as we do not have this in Java AST tree.

done

Please add code examples to "Access Java AST from Javadoc Check"

done

Does it make sense to place them as table ? Example:

done. Transformed to the table.

Please put a link to github issue to make javadoc customizable at Overview chapter .
Please post a note to issue to update xdoc on completion.

done

Please make all class names and methods to be a link to javadoc.

done

We need to explain user what version of HTML we support . How we can support HTML5, and any further versions.

done

Contributor

baratali commented May 10, 2016

We need to explain a reason why we continue parsing even javadoc content is not XHTML

done

We need to explain why we have in AST (CHAR, WS), as we do not have this in Java AST tree.

done

Please add code examples to "Access Java AST from Javadoc Check"

done

Does it make sense to place them as table ? Example:

done. Transformed to the table.

Please put a link to github issue to make javadoc customizable at Overview chapter .
Please post a note to issue to update xdoc on completion.

done

Please make all class names and methods to be a link to javadoc.

done

We need to explain user what version of HTML we support . How we can support HTML5, and any further versions.

done

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani May 11, 2016

Member

However result tree will be unpredictable.

So predictable or not predictable ?

In Javadoc comment every whitespace matters, so parse tree contains whitespace nodes (WS javadoc token type). So do CHAR javadoc token that presents single character. The only redundancy Javadoc tree has because of this is that TEXT node consists of CHAR and WS nodes which is useless, but it is implementation nuance.

We need to rephrase this paragraph. I do not understand it.

(In future we will try to resolve this)

please open the issue and make a link.

Member

romani commented May 11, 2016

However result tree will be unpredictable.

So predictable or not predictable ?

In Javadoc comment every whitespace matters, so parse tree contains whitespace nodes (WS javadoc token type). So do CHAR javadoc token that presents single character. The only redundancy Javadoc tree has because of this is that TEXT node consists of CHAR and WS nodes which is useless, but it is implementation nuance.

We need to rephrase this paragraph. I do not understand it.

(In future we will try to resolve this)

please open the issue and make a link.

baratali added a commit to baratali/checkstyle that referenced this issue May 11, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 11, 2016

romani added a commit that referenced this issue May 11, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 12, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 12, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani May 22, 2016

Member
  1. missed links for getDefaultJavadocTokens(), visitJavadocToken in section "How to create Javadoc Check"

Tags do not require closing tag
don't need closing tag

that is from section "HTML code in javadoc comments".
It is not clear, look like the same. Lets extend documentation with links to definition of singleton tag and .... and lets make an examples.

html code in javadoc comments
if Checkstyle meat unknown tag it does not fail ....

What if HTML5 tag is present but not closed ?

Member

romani commented May 22, 2016

  1. missed links for getDefaultJavadocTokens(), visitJavadocToken in section "How to create Javadoc Check"

Tags do not require closing tag
don't need closing tag

that is from section "HTML code in javadoc comments".
It is not clear, look like the same. Lets extend documentation with links to definition of singleton tag and .... and lets make an examples.

html code in javadoc comments
if Checkstyle meat unknown tag it does not fail ....

What if HTML5 tag is present but not closed ?

baratali added a commit to baratali/checkstyle that referenced this issue May 25, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 25, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 25, 2016

@baratali

This comment has been minimized.

Show comment
Hide comment
@baratali

baratali May 25, 2016

Contributor
  1. missed links for getDefaultJavadocTokens(), visitJavadocToken in section "How to create Javadoc Check"

Done

Tags do not require closing tag
don't need closing tag
that is from section "HTML code in javadoc comments".
It is not clear, look like the same. Lets extend documentation with links to definition of singleton tag and .... and lets make an examples.

Done

html code in javadoc comments
if Checkstyle meat unknown tag it does not fail ....
What if HTML5 tag is present but not closed ?

Done

Contributor

baratali commented May 25, 2016

  1. missed links for getDefaultJavadocTokens(), visitJavadocToken in section "How to create Javadoc Check"

Done

Tags do not require closing tag
don't need closing tag
that is from section "HTML code in javadoc comments".
It is not clear, look like the same. Lets extend documentation with links to definition of singleton tag and .... and lets make an examples.

Done

html code in javadoc comments
if Checkstyle meat unknown tag it does not fail ....
What if HTML5 tag is present but not closed ?

Done

baratali added a commit to baratali/checkstyle that referenced this issue May 25, 2016

romani added a commit that referenced this issue May 25, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 28, 2016

baratali added a commit to baratali/checkstyle that referenced this issue May 28, 2016

romani added a commit that referenced this issue May 28, 2016

romani added a commit that referenced this issue Jun 1, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jun 1, 2016

Member

I did some minor changes.

For "Limitation" chapter.
Smth is not good.... We expect non XHTML structure(we are not failing) so all Javadoc check have to expect non-nested AST. It will create a lot of problems to write reliable Javadoc Check, as amount of false positives will be huge.
We need somehow to allow Check to decide to skip execution on Javadoc that is not XHTML , to let author of Check decide to support non-nested AST or not.
Can we somehow grab from parser a flag that javadoc is not xhtml ? (separate issue)
We should raise violation by Check if it can not be executed on non-XHTML javadoc ? (separate issue)
We need Check that will validate XHTML structure, please create an issue.

tags that are "don't require closing tag"

can you provide link to this term ?

and a list of tags whose end tag is forbidden (also known as empty html tags

What does "forbidden" mean ? content is not allowed ?
http://www.colorglare.com/2014/02/03/to-close-or-not-to-close.html
It is not, and has never been, valid HTML to write <br></br>, since this would imply that the br element accepts content (writing <br>Hello!</br> has absolutely no meaning).

Here is a term - https://www.w3.org/TR/html-markup/syntax.html#void-element - please use only it in the documentation.
Here is clear description that "/" is optional for void elements - Optionally, a "/" character, which may be present only if the element is a void element.
If we demand "/" to be present we should clearly state that in limitations.
Example: https://www.w3.org/TR/html-markup/li.html#li-tags

The comment should be written in XHTML to build nested AST Tree that most Checks expect.

We are not XHTML , we similar to XHTML, see http://www.w3schools.com/html/html_xhtml.asp
xhtml has a lot of restrictions that we do not demand.
We can not use XHTML term, we need to define what rules of XHTML we relaxed.

Base on discussion at #2839 .

We support html4 tags in grammar for now only. It mean if any html5 tag that "that don't require closing tag" is appeared in javadoc content parser will fail. But javadoc is completely correct from html perspective.
That mean that we need to add to grammar all html5 , html6 ,..... htmlX tags that "that don't require closing tag". We could add it by user request.
But such nuance HAS to be added to our HTML page.

we need to describe behaviour about "non-supported" tags - http://www.w3schools.com/tags/default.asp . In my opinion we have to parse them as we did before, some custom Check will do validation.

from #2839

Notice, however, that the different versions of HTML have different rules concerning closing tags </li> and self-closing tags <br />.

we need to investigate this.

Member

romani commented Jun 1, 2016

I did some minor changes.

For "Limitation" chapter.
Smth is not good.... We expect non XHTML structure(we are not failing) so all Javadoc check have to expect non-nested AST. It will create a lot of problems to write reliable Javadoc Check, as amount of false positives will be huge.
We need somehow to allow Check to decide to skip execution on Javadoc that is not XHTML , to let author of Check decide to support non-nested AST or not.
Can we somehow grab from parser a flag that javadoc is not xhtml ? (separate issue)
We should raise violation by Check if it can not be executed on non-XHTML javadoc ? (separate issue)
We need Check that will validate XHTML structure, please create an issue.

tags that are "don't require closing tag"

can you provide link to this term ?

and a list of tags whose end tag is forbidden (also known as empty html tags

What does "forbidden" mean ? content is not allowed ?
http://www.colorglare.com/2014/02/03/to-close-or-not-to-close.html
It is not, and has never been, valid HTML to write <br></br>, since this would imply that the br element accepts content (writing <br>Hello!</br> has absolutely no meaning).

Here is a term - https://www.w3.org/TR/html-markup/syntax.html#void-element - please use only it in the documentation.
Here is clear description that "/" is optional for void elements - Optionally, a "/" character, which may be present only if the element is a void element.
If we demand "/" to be present we should clearly state that in limitations.
Example: https://www.w3.org/TR/html-markup/li.html#li-tags

The comment should be written in XHTML to build nested AST Tree that most Checks expect.

We are not XHTML , we similar to XHTML, see http://www.w3schools.com/html/html_xhtml.asp
xhtml has a lot of restrictions that we do not demand.
We can not use XHTML term, we need to define what rules of XHTML we relaxed.

Base on discussion at #2839 .

We support html4 tags in grammar for now only. It mean if any html5 tag that "that don't require closing tag" is appeared in javadoc content parser will fail. But javadoc is completely correct from html perspective.
That mean that we need to add to grammar all html5 , html6 ,..... htmlX tags that "that don't require closing tag". We could add it by user request.
But such nuance HAS to be added to our HTML page.

we need to describe behaviour about "non-supported" tags - http://www.w3schools.com/tags/default.asp . In my opinion we have to parse them as we did before, some custom Check will do validation.

from #2839

Notice, however, that the different versions of HTML have different rules concerning closing tags </li> and self-closing tags <br />.

we need to investigate this.

@baratali

This comment has been minimized.

Show comment
Hide comment
@baratali

baratali Jun 9, 2016

Contributor

#3311
#3313

  1. As I know there is no special term for this kind of tags.
    It's described differently:
    element’s end tag may be omitted - https://www.w3.org/TR/html-markup/p.html#p
    End tag is Optional - https://www.w3.org/TR/html4/index/elements.html

I've change tags that are "don't require closing tag" to elements whose end tag is optional.

What does "forbidden" mean ? content is not allowed ?

End tag is Forbidden - I took this from here: https://www.w3.org/TR/html4/index/elements.html. It means there is no End tag and, therefore, no content.

Here is a term - https://www.w3.org/TR/html-markup/syntax.html#void-element - please use only it in the documentation.

Such tags are also called "empty tags" (as I described in wiki): https://www.w3.org/TR/html4/struct/text.html#edef-BR
http://www.w3schools.com/html/html_elements.asp
But, I agree, void elements term is more suitable.

  1. "XHTML-style rules" section has been added.

  2. Done

  3. Done

#3332

Contributor

baratali commented Jun 9, 2016

#3311
#3313

  1. As I know there is no special term for this kind of tags.
    It's described differently:
    element’s end tag may be omitted - https://www.w3.org/TR/html-markup/p.html#p
    End tag is Optional - https://www.w3.org/TR/html4/index/elements.html

I've change tags that are "don't require closing tag" to elements whose end tag is optional.

What does "forbidden" mean ? content is not allowed ?

End tag is Forbidden - I took this from here: https://www.w3.org/TR/html4/index/elements.html. It means there is no End tag and, therefore, no content.

Here is a term - https://www.w3.org/TR/html-markup/syntax.html#void-element - please use only it in the documentation.

Such tags are also called "empty tags" (as I described in wiki): https://www.w3.org/TR/html4/struct/text.html#edef-BR
http://www.w3schools.com/html/html_elements.asp
But, I agree, void elements term is more suitable.

  1. "XHTML-style rules" section has been added.

  2. Done

  3. Done

#3332

baratali added a commit to baratali/checkstyle that referenced this issue Jun 9, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jun 9, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jun 10, 2016

romani added a commit that referenced this issue Jun 10, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jun 14, 2016

romani added a commit that referenced this issue Jun 14, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jun 15, 2016

romani added a commit that referenced this issue Jun 15, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jul 10, 2016

romani added a commit that referenced this issue Jul 11, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jul 12, 2016

baratali added a commit to baratali/checkstyle that referenced this issue Jul 12, 2016

romani added a commit that referenced this issue Jul 12, 2016

romani added a commit that referenced this issue Jul 17, 2016

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jul 17, 2016

Member

current state is good to be final. Issue is closed.

Member

romani commented Jul 17, 2016

current state is good to be final. Issue is closed.

@romani romani closed this Jul 17, 2016

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