search

yegor256 / qulice

Quality Police for Java projects: aggregator of Checkstyle and PMD
https://www.qulice.com
Other
299 stars 110 forks source link

validate javadoc comments formatting #10

Open yegor256 opened 11 years ago

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 2-Oct-2011 8:30am

We should validate that JavaDoc comments are properly formatted. Maybe javadoc native utility can be used, or a custom tool.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 16-Oct-2011 3:34pm

All src/main/java and src/test/java classes should be validated. Javadoc warnings or errors should lead to a broken build.

The budget is 2 hours (including unit test and integration test). If the budget is not enough you can use PDD concept to break the task to smaller ones.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 16-Oct-2011 7:13pm

Ivan, this task is for you. The task is a little tricky, since it may be implemented in a few different ways. Please, discuss before implementing.

Keep in mind that we work in branches only: [http://www.tpc2.com/dev/branches]

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 16-Oct-2011 7:24pm

wait until #15 is closed

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 17-Oct-2011 3:11pm

You can go ahead, I finished refactoring in #15

yegor256 commented 11 years ago

migrated from Trac, where originally posted by kotelkin.ivan on 17-Oct-2011 6:03pm

There is comment in #15, that checkstyle tool is migrated to own module qulice-checkstyle. Could you please clarify the following questions:

  1. just to double-check: should i extend the functionality of JavadocTagsCheck check?
  2. As I see, you are trying to extend checkstyle abilities of checking javadocs. So, could you please provide the examples what javadocs do treat invalid. Cause default checkstyle functionality provides strict enough validation of javadocs.
yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 17-Oct-2011 6:08pm

I think that we should create a new module qulice-javadoc, which will run full-cycle javadoc validation of the project code, and catch all reported warnings/errors from Javadoc tool.

Checkstyle is a good tool, but it can only check formatting. It doesn't check more deeper problems, like @see #method() broken links, for example. Or any kind of incorrect javadoc tags.

Somehow we should make sure that the project complies with Requirements for Writing Java API Specifications. Checkstyle is not a big help here..

yegor256 commented 11 years ago

migrated from Trac, where originally posted by kotelkin.ivan on 18-Oct-2011 4:54pm

we should create a new module So, what will be the entry point to the module code execution? I mean will it be a standalone command-line tool? Or maybe a maven plugin?

all reported warnings/errors from Javadoc tool I have analyzed the javadoc tool abilities. Yes, it can validate links consistency. But it cannot report missing javadocs or required params, @author tags and so on. It is very tolerant.

So I suppose we have to combine outputs/results from serveral utils complementing each other. E.g. checkstyle (with yout custom JavadocTagsCheck) and javadoc.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 18-Oct-2011 5:51pm

We already validate what we can with CheckstyleValidator from qulice-checkstyle. What we should create in this ticket is a new module qulice-javadoc and one class inside it: JavadocValidator implements com.qulice.spi.Validator. This class should call javadoc (somehow) and understand its output. If there are some problems - report.

Maybe you know some other more strict tools for javadoc validation?

ps. Don't forget to re-assign the ticket back to me when you need an answer or my attention.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by kotelkin.ivan on 19-Oct-2011 10:20am

We will try to find some other utility. Cause for now it seems that the only useful feature of standard javadoc tool is validating links consistency.

Extracting output is not a big deal.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 19-Oct-2011 4:07pm

What about doxygen? BTW, take a look: http://stackoverflow.com/questions/2580215

yegor256 commented 11 years ago

migrated from Trac, where originally posted by kotelkin.ivan on 19-Oct-2011 5:07pm

Yeah I've seen that topic. Dont know. Will need time to analyze.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 20-Oct-2011 6:08pm

Ivan is no longer in the project.

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor256 on 22-Jan-2012 11:39pm

Milestone PROTOTYPE deleted

yegor256 commented 11 years ago

migrated from Trac, where originally posted by yegor on 21-Apr-2013 12:03pm

we moved to Github

krzyk commented 8 years ago

@davvd valid bug

davvd commented 8 years ago

@davvd valid bug

@krzyk I tagged this as "bug"

krzyk commented 8 years ago

@davvd it is postponed

davvd commented 8 years ago

@yegor256 thanks a lot for reporting, 15 mins added to your acc, pmt ID 000-886e25be

davvd commented 8 years ago

@davvd it is postponed

@krzyk sure, thanks, I added "postponed" label to it

davvd commented 8 years ago

@davvd it is postponed

@krzyk all right, we'll find someone else for this task