[CRYPTO] Documenting the public API before it is too late...

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[CRYPTO] Documenting the public API before it is too late...

sebb-2-2
There does not currently seem to be any indication of which classes
are part of the public API and which are only public or protected
because of the restrictions of the Java permission scheme.

Since there has so far been no release, this is the ideal time to
document which APIs are intended to be public, and which are
definitely not.

If the distinction can be made now, then it will make changes to
implementation classes much easier in the future.

One such way is to move all the non-API classes into a separate
/internal/ package hierarchy.
The advantages of this are:
- self-documenting
- easy to check which public classes use the internal classes; in
particular that they are not used as parameter or return types.
- easy to exclude the internal classes from Clirr or other compatibility reports

Other schemes are of course possible.

But please can we document the public API before it is too late?

Thanks!

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [CRYPTO] Documenting the public API before it is too late...

jochen-2
On Wed, Jun 15, 2016 at 11:20 AM, sebb <[hidden email]> wrote:

> But please can we document the public API before it is too late?

+1

Jochen


--
The next time you hear: "Don't reinvent the wheel!"

http://www.keystonedevelopment.co.uk/wp-content/uploads/2014/10/evolution-of-the-wheel-300x85.jpg

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: [CRYPTO] Documenting the public API before it is too late...

Ke, Xianda
In reply to this post by sebb-2-2
Thanks sebb for the feedback. All the  implementation classes shouldn't public. we are working on this.
A JIRA (CRYPTO-71) was already created for the cipher implementation classes. We will continue.

Regards,
Xianda

-----Original Message-----
From: sebb [mailto:[hidden email]]
Sent: Wednesday, June 15, 2016 5:20 PM
To: CommonsDev
Subject: [CRYPTO] Documenting the public API before it is too late...

There does not currently seem to be any indication of which classes are part of the public API and which are only public or protected because of the restrictions of the Java permission scheme.

Since there has so far been no release, this is the ideal time to document which APIs are intended to be public, and which are definitely not.

If the distinction can be made now, then it will make changes to implementation classes much easier in the future.

One such way is to move all the non-API classes into a separate /internal/ package hierarchy.
The advantages of this are:
- self-documenting
- easy to check which public classes use the internal classes; in particular that they are not used as parameter or return types.
- easy to exclude the internal classes from Clirr or other compatibility reports

Other schemes are of course possible.

But please can we document the public API before it is too late?

Thanks!

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]