In clean code book, there is a point that says "Javadocs in Public APIs".
And the same for Effective java book, there is this item :
"Item 56: Write doc comments for all exposed API elements".
So this is my question "Are all public methods considered public APIs?"
On
It depends.
An API is what a developer uses in order to achieve something
Are we talking about a Java library which does X ?
Well, any public method is part of the API.
An API can even be:
A set of solutions that allow the developer to achieve a certain result
Not necessarily a single public method produces a valuable output and it may be necessary in some cases to uses other methods to reach a meaningful output, still those procedures are part of the API.
I'd like to point out that an API (at least in Java) should be made of "public final" methods, because methods shouldn't be override by the caller. Clearly, we have to look at the context we are talking about, in some restricted cases you may want to allow it.
I have a really good source for you about this topic.
Recently i came across this video The art of building Java APIs: Do’s and Don’ts
made by Jonathan Giles (Java Guy at Microsoft) which explores the best and worst
practices about building API and it talks about Effective Java and covers some topics of the book.
(Those parts are highlighted while watching it).
Anyway, surely an interesting question.
On
They are different things for me.
Public API is the API that is announced and published to the world to use. So it is expected that many clients that you do not have control will use it. That also means it is more difficult to change as you need to consider the backward compatibility and that sort of thing if you want to make sure that any changes will not break the existing clients. Hence they should be well documented in javadocs to describe the actual behavior.
Pubic method is just a java method declared as public. You can declare a public method just for internal use , and it this case it is not the public API. Since it is only used internally , you have total control on the clients that use it .It is much more easy to change the API signature and its behaviour as you can change these clients to adapt to the new changes.
Also see this article for the distinction between published and public is actually more important than that between public an private.
A public API is exposed by means of public methods. A public method alone may not be an API. If the the question is if an API can be made of methods in "normal" classes that are not REST points, the answer is yes.