How to document experimental or incomplete APIs like @deprecated?

Posted by Michael Levy on Programmers See other posts from Programmers or by Michael Levy
Published on 2012-10-15T19:38:47Z Indexed on 2012/10/15 21:48 UTC
Read the original article Hit count: 273

Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely change? (Yeah, I know, those methods shouldn't be public, yada yada yada. I didn't create my situation, I'm just trying to make the best of it.)

What do people suggest? Experimental, Incomplete, something else?

If I'm building javadoc documentation for this API that is still in flux, should I use the @deprecated tag or is there a better convention? To me @deprecated implies that this API is old and a newer preferred mechanism is available. In my situation, there is no alternative, but some of the methods in the API are not finished and so should not be used. At this point I cannot make them private, but I'd like to put clear warnings in the docs.

© Programmers or respective owner

Related posts about documentation

Related posts about terminology