search

asciidoctor / asciidoclet

:clipboard: A Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
https://github.com/asciidoctor/asciidoclet
Apache License 2.0
132 stars 40 forks source link

Added Asciidoc processing class filtering to allow for graceful migrations #91

Closed johncarl81 closed 2 years ago

johncarl81 commented 6 years ago

Addresses https://github.com/asciidoctor/asciidoclet/issues/90

mojavelinux commented 5 years ago

You might consider adding @gsmet to the list of reviewers.

johncarl81 commented 5 years ago

Went ahead and squashed... slipped my mind that those were defined for javadoc, good catch @gsmet. Do you have a suggestion for replacement options?

gsmet commented 5 years ago

As for the options, I think I would have added an asciidoclet prefix to all the asciidoclet specific options. That would make it clearer and avoid potential conflicts.

Something like --asciidoclet-include, --asciidoclet-exclude and potentially (but unrelated) --asciidoclet-attribute and so on (and I would still support the old syntax for compatibility purposes).

The latter point is out of the scope of this PR but I think it would be nice to be consistent.

Currently, the only difference between standard options and specific options is the fact that the standard option has only one dash. It's a bit weird.

johncarl81 commented 5 years ago

I like being a bit more specific with the options, but I don't think we need to go as far as qualifying them specifically for asciidoclet as there can be only one doclet configured. How about--include-asciidoclet-process and --exclude-asciidoclet-process?

gsmet commented 5 years ago

@johncarl81 sorry for the late reply. Your proposal looks good to me if you don't want to qualify all the options.

johncarl81 commented 5 years ago

Ok, made those updates... final review time @mojavelinux @msgilligan @gsmet ?

gsmet commented 4 years ago

@johncarl81 hmmm, totally missed your last message, do you mind updating the PR as it says it's out of date? Once it's done, I'll do some final testing with Hibernate ORM and Quarkus.

Thanks!

johncarl81 commented 4 years ago

Ok, done @gsmet. Let me know if you need anything.

lptr commented 2 years ago

This would be very useful to us at https://github.com/gradle/gradle. Any chance to get the PR merged?

mojavelinux commented 2 years ago

This PR seemed to have gotten approved, then stuck. For anyone who previously reviewed it, are you still comfortable moving forward with it?

My only hangup is the name of the options. To me, --include-asciidoclet-process doesn't read very well as a phrase. I would prefer to see one of these:

If you have other suggestions, please raise them.

mojavelinux commented 2 years ago

If there are no objections in the next 24-48 hours, I will merge this PR.

johncarl81 commented 2 years ago

I like staying somewhat specific here because this filter is for asciidoclet and not the full processing of javadocs. So, I could see us using --asciidoclet-include / --asciidoclet-exclude if we want to be a little more concise. If I get a yay on this, I'll go ahead and make the change.

johncarl81 commented 2 years ago

And just an unfortunate reminder here.. this only applies to the Java 8 doclet.

johncarl81 commented 2 years ago

ok, review and merge @mojavelinux ?

mojavelinux commented 2 years ago

You can go ahead and merge. I was only jumping in to help...but if you've got it, go for it.

mojavelinux commented 2 years ago

:beers: