validate javadoc comments formatting about qulice

[yegor256]

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]

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]

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

wait until #15 is closed

[yegor256]

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

You can go ahead, I finished refactoring in #15

[yegor256]

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]

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]

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]

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]

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]

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]

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]

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

Ivan is no longer in the project.

[yegor256]

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

Milestone PROTOTYPE deleted

[yegor256]

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

we moved to Github

[krzyk]

@davvd valid bug

[davvd]

@davvd valid bug

@krzyk I tagged this as "bug"

[krzyk]

@davvd it is postponed

[davvd]

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

[davvd]

@davvd it is postponed

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

[davvd]

@davvd it is postponed

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