mbeckerle commented on PR #1112:
URL: https://github.com/apache/daffodil/pull/1112#issuecomment-1810716932
> +1
>
> I looked at the javadoc and it doesn't include any of the new stuff since
it's not in the japi project. That's expected, and doesn't have to be fixed for
this PR, but we should make sure that is addressed at some point, maybe once
the drill integration is complete and we are confident that the new API is
sufficient.
Yeah, we have to look into how to make the doc "hang together" despite some
of the code being defined in java and some (most really) in scala, and some
being in japi/sapi packages and some in runtime1/api package.
We may have to put in our own relative hyperlinks between the two bodies of
documentation.
We also really need a way to document and exclude some methods/members from
the API without having to have a sharp separation between things in the
sapi/japi packages which are *all* API, and things not. We need to avoid the
overhead of this proxy japi/sapi structure. It's too hard to maintain. I'd be
fine with just adding to the java/scaladoc a standard comment and naming
convention indicating that a method is internal not to be considered part of
the API. These methods do need to be public. Even just naming them with prefix
"_" and always putting them last in the trait/class/object would be ok.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
