Opened 4 years ago

Closed 4 years ago

#16767 closed enhancement (duplicate)

Javadoc doesn't include any of the documentation.

Reported by: leeroy Owned by: karsten
Priority: Low Milestone:
Component: Metrics/Library Version:
Severity: Keywords:
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

When generating documentation using javadoc the result doesn't include any of the code documentation. The cause is some minor problems with the documentation style. This can be done using the build file to improve the generated documentation with an ant task. Otherwise it requires changing all of the non-impl to at least generate *some* documentation.

I attach a sample of the fixed documentation. With slight differences due to the origin.

Child Tickets

Attachments (1)

docs.tar.xz (103.8 KB) - added by leeroy 4 years ago.

Download all attachments as: .zip

Change History (18)

comment:1 Changed 4 years ago by iwakeh

Hi leeroy, thanks for looking into this!

Could you also attach the patch of the changes of the build.xml and/or other sources?

Thanks!

Changed 4 years ago by leeroy

Attachment: docs.tar.xz added

comment:2 Changed 4 years ago by leeroy

Yes I can. Are you looking for just the main documentation, or including tests as well? If the tests are included without changing the package-name they end up in impl. Which looks ugly, and it doesn't seem right.

Changing the commenting and putting tests in impl versus also changing package-names. The updated docs sample shows the latter.

Aside: I heard there's a vulnerability in javadoc up to build 1.6? Which is what metrics-lib uses. It might be worth reconsidering this. As far as I'm aware using 1.7 to build the docs doesn't have the problem because it applies fixes manually?

Last edited 4 years ago by leeroy (previous) (diff)

comment:3 Changed 4 years ago by karsten

Status: newneeds_information

Did you include a patch somewhere? I can't seem to find it.

Tests are in the same package as implementation classes on purpose, so that they can access package-visible classes and methods. We shouldn't move tests to another package, because we'd lose that ability then.

We shouldn't switch to Java 1.7 only because we have heard of a Javadoc vulnerability in 1.6. I guess if there's really a vulnerability, it'll be fixed in 1.6, too. Also, developers are only generating docs locally, so even if there's a vulnerability, there's not much it can do. Of course, if you can provide more specifics, let us know.

comment:4 Changed 4 years ago by iwakeh

I second Karsten about the jdk version and not renaming any test packages.

The javadocs without tests is sufficient for the start. I think there are hardly any comments
in the test classes that would be helpful as javadoc, i.e. meaningful without the code beside them.

So, having a patch for the comments in non-test classes and an additional javadoc ant task would be great.

comment:5 Changed 4 years ago by leeroy

I only mention the javadoc vulnerability up to 1.6 because even after setting the build version *back* to 1.6 I still get a warning when compiling using ant. Whether you decide to fix that is up to you.

I moved the tests in my fork. Your concerns are unmerited. Tests should be documented better, and *will* be, in my fork going forward. Just to prove you concerns make no sense I'm going to leave the tests and you can decide whatever you decide.

If you're sure you want a patch let me know. It's a big and ugly file. Instead have a repo and I'll make the patch if you still really want it.

git://5kcvwhdavdpsyui2.onion:8080/metrics-lib.git

comment:6 Changed 4 years ago by karsten

Resolution: wontfix
Status: needs_informationclosed

Big and ugly you say? No, thanks.

comment:7 Changed 4 years ago by leeroy

Yes, a big and ugly looking (lacking makeup for failing style). As in it fixes all the comments which were never fixed, which produces documentation that never existed.

Good to see you're consistent.

comment:8 Changed 4 years ago by leeroy

Resolution: wontfix
Status: closedreopened

comment:9 Changed 4 years ago by leeroy

It's selfish for you to assume that just because you can't be bothered to review fixes to their code, that no one else would.

Reopened so that anyone who actually wants the documentation can get it.

Last edited 4 years ago by leeroy (previous) (diff)

comment:10 Changed 4 years ago by iwakeh

Resolution: wontfix
Status: reopenedclosed

comment:11 Changed 4 years ago by leeroy

Resolution: wontfix
Status: closedreopened

Is that the kind of community you live in now? I see you're no better than those who hate tor. I thought you were better. Aren't you supposed to be better? That's what you make pretenses at.

comment:12 Changed 4 years ago by leeroy

Oh, look at us were tor project an open source advocating community. We love help with improving our software. Won't accept criticism for the benefit of the community. Nope. Even if it makes things better. Won't review code. Even when it's a fix.

I paraphrase from readme's: Documentation needs fixing.

Now you won't even review the fix? And you refuse to acknowledge the problem. Shall I provide a link to show your contradiction. On top of that you hide the problem. Instead of allowing the community to decide.

Yup, sounds selfish. No community here.

comment:13 Changed 4 years ago by nickm

Status: reopenedneeds_revision

We take patches; but they have to be good clean ones. We offer advice in helping people make their patches good and clean; but we have no power to compel people to listen.

Ultimately, I am sorry that you didn't find our community to meet the ideals of open-source software development. I sincerely wish you the best of fortune finding another community that suits your needs, your desires, and your preferred interaction style.

(Leaving as needs_revision since the appearance to me is that there could conceivably be an issue here in need of a clean fix.)

comment:14 Changed 4 years ago by leeroy

So is metrics-lib, like, Karsten's. Only Karsten's, by Karsten, for Karsten? If you provide a fix that doesn't fit into a conceptual system, then it's not a fix? Won't review? Even when it's for the better of anyone who uses metrics-lib.

Karsten, did you not ask for documentation improvements? In an email. Were your thanks then mere pretenses too? I fix your code, you don't like it. I fix your comments, and now there's documentation, but once again you don't like it.

comment:15 in reply to:  13 Changed 4 years ago by leeroy

Replying to nickm:

We take patches; but they have to be good clean ones. We offer advice in helping people make their patches good and clean; but we have no power to compel people to listen.

Ultimately, I am sorry that you didn't find our community to meet the ideals of open-source software development. I sincerely wish you the best of fortune finding another community that suits your needs, your desires, and your preferred interaction style.

(Leaving as needs_revision since the appearance to me is that there could conceivably be an issue here in need of a clean fix.)

I think you misunderstand Nick. If the fix looks ugly, it's because of how it was originally implemented. The fix is clean. Much better. I don't like to quote percentages. Karsten didn't even review the fix. If they had they would have seen it's vastly better.

I even went to the effort of creating a gitweb and repo. Just to make it easy. So don't give me that it's not clean, or it needs cleaning up. I fixed the problem, Karsten could at least make an effort.

Last edited 4 years ago by leeroy (previous) (diff)

comment:16 in reply to:  13 Changed 4 years ago by leeroy

Replying to nickm:

Ultimately, I am sorry that you didn't find our community to meet the ideals...

Don't give me that ideals bs either. Based on your response you assume a review was done and the fix is ugly. From a naive perspective that may actually be the case (in that no effort was made, and this is acceptable).

From what you describe Nick, you agree with my sentiments. Karsten should be apologizing to *you*. I'm sorry you got involved.

comment:17 Changed 4 years ago by iwakeh

Resolution: duplicate
Status: needs_revisionclosed

Closed, b/c it'll be handled in #16873, where we have clear steps for improvement.

Note: See TracTickets for help on using tickets.