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

ImportControl: improve xdoc documentation #2935

Open
romani opened this Issue Feb 18, 2016 · 4 comments

Comments

Projects
None yet
2 participants
@romani
Member

romani commented Feb 18, 2016

http://checkstyle.sourceforge.net/config_imports.html#ImportControl

It contains documentation on each of the elements and attributes.

It is required to inline them to html.
It is required to give example for each attribute and human explanation what is expected to be validated.

which is part of the Checkstyle distribution.

distribution --> code

https://github.com/checkstyle/checkstyle/blob/master/config/import-control.xml

change to use all attributes of ImportControl Check in this file
put comments to explain a meaning.

@romani romani added the approved label Feb 18, 2016

@jochenvdv

This comment has been minimized.

Show comment
Hide comment
@jochenvdv

jochenvdv Feb 16, 2017

Contributor

Please assign me.

Javadoc for ImportControlCheckshould also contain some examples. Other checks do this. This should probably be done in this issue.

Also, the comments in the import control DTD should be updated (they still mention Guard) and be linked to from xdocs.

which is part of the Checkstyle distribution.
distribution --> code

This makes it sound as if the config file is included with Checkstyle for other people to use, like for example the Google config. I think we should refer to it as "Checkstyle's own import control configuration".

So, 4 things need to be done: xdocs, javadoc, dtd and commenting the import control config.
Shall I do this in separate commits?

Contributor

jochenvdv commented Feb 16, 2017

Please assign me.

Javadoc for ImportControlCheckshould also contain some examples. Other checks do this. This should probably be done in this issue.

Also, the comments in the import control DTD should be updated (they still mention Guard) and be linked to from xdocs.

which is part of the Checkstyle distribution.
distribution --> code

This makes it sound as if the config file is included with Checkstyle for other people to use, like for example the Google config. I think we should refer to it as "Checkstyle's own import control configuration".

So, 4 things need to be done: xdocs, javadoc, dtd and commenting the import control config.
Shall I do this in separate commits?

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Feb 16, 2017

Member

Javadoc for ImportControlCheckshould also contain some examples. Other checks do this. This should probably be done in this issue.

you can skip it.
FYI: we thinking about generation of xdoc from javadoc and unification of documentation and meta-data model.
https://groups.google.com/forum/#!topic/checkstyle-devel/lsNF6Dj90lo

This makes it sound as if the config file is included with Checkstyle for other people to use

no reason to share it with other. just wording need to be changed.
Distribution now is maven JAR artifact and "....-all.jar" with compiled classes that could be used by user.
text in xdoc should be "source code repository".

Shall I do this in separate commits?

yes, it will ease code review and speedup merge process. It will allow you to put some stuff to next release even not whole issue is done.

Member

romani commented Feb 16, 2017

Javadoc for ImportControlCheckshould also contain some examples. Other checks do this. This should probably be done in this issue.

you can skip it.
FYI: we thinking about generation of xdoc from javadoc and unification of documentation and meta-data model.
https://groups.google.com/forum/#!topic/checkstyle-devel/lsNF6Dj90lo

This makes it sound as if the config file is included with Checkstyle for other people to use

no reason to share it with other. just wording need to be changed.
Distribution now is maven JAR artifact and "....-all.jar" with compiled classes that could be used by user.
text in xdoc should be "source code repository".

Shall I do this in separate commits?

yes, it will ease code review and speedup merge process. It will allow you to put some stuff to next release even not whole issue is done.

@jochenvdv

This comment has been minimized.

Show comment
Hide comment
@jochenvdv

jochenvdv Feb 18, 2017

Contributor

@romani Should I update all versions of the import control DTD? Or only the latest one?

Contributor

jochenvdv commented Feb 18, 2017

@romani Should I update all versions of the import control DTD? Or only the latest one?

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Feb 18, 2017

Member

Only the latest, previous versions exists only to support old versions of checkstyle. Existing configurations most likely already do not need help with config.

Member

romani commented Feb 18, 2017

Only the latest, previous versions exists only to support old versions of checkstyle. Existing configurations most likely already do not need help with config.

jochenvdv added a commit to jochenvdv/checkstyle that referenced this issue Feb 19, 2017

romani added a commit that referenced this issue Feb 19, 2017

@checkstyle checkstyle deleted a comment from jochenvdv Apr 20, 2018

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