Separation between normal classes and Exception classes is not 100% reliable #175

Closed
lorenzos opened this Issue Sep 19, 2012 · 5 comments

Projects

None yet

3 participants

@lorenzos

And cannot be.

In my custom library I defined some Exception classes, that do not extend Exception directly, but extend a SomeLibException class that extends Exception directly:

// Some lib framework
class SomeLibException extends Exception

// My project library
 class MyCustomException extends SomeLibException

Now the problem is that if I did not want to include all the big Some lib framework in my documentation, Apigen cannot determine that MyCustomException is a grand-child of Exception, and so, is not listed as Exception is my generated documentation.

If there's not a way to make it work as excepted, maybe an extra non-standard javadoc keyword should be added to tell Apigen if a class should be listed as Exception.

@Andrewsville
Contributor

You're right. The only solution would be an extra annotation. I suggest annotating the class @exception. It is not standard but clear enough IMO. (And the change in ApiGen itself would be trivial). Any thoughts @kukulich?

@Andrewsville
Contributor

There might be another solution. Instead of --exclude the framework you can --skip-doc-path it. Its sources will be parsed (which will make ApiGen run slower) but it won't be part of the documentation. And the class tree will probably make more sense because it will contain names of classes from the framework (if they have any subclasses in your project). Give it a try a let us know.

@TomasVotruba
Contributor

@lorenzos Was this solution sufficient for you?

@lorenzos

Sincerely, I do not remember if I tried the solution, it was almost 2 year ago. Anyway, if you were asking it just to know if the issue can be closed, I just made a quick test with --skip-doc-path and, for me, it works good. So yes, for me it is sufficient.

@TomasVotruba
Contributor

Yea, that's the reason. I'm glad it works for you.

Thank you

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