Re: [Libmesh-devel] Should we introduce "deprecated()" and "experimental()"?

[Derek G. <fri...@gm...>]

I feel like I should chime in here... but I really don't have much
experience in this area.

The one thing that I've seen done, is just put out some documenation
about what will be deprecated when... and what interfaces are
experimental.

We could employ the doxygen tag @deprecated for this purpose... and
either create a tag for @experimental or @unstable (I like unstable
myself... meaning the API could change).  We should be able to use
Doxygen to create pages specifically listing all deprecated and
unstable pieces of the code for quick reference.

I'm wary of actually putting things into the code itself.  For
instance would you wrap that experimental() call in #ifdefs so that it
wouldn't execute if compiled in opt?  If so then we are going to end
up with a helluva lot of ifdefs... and a lot of different defs
(describing what versions) running around the code... which always
looks cluttered.  If not... then you will incur the function call
overhead everytime you pass through there.

What I'm trying to say is that I think the idea to let the users know
what's going on is a great idea... but at the same time we should
trust our users enough in their ability to read the documentation for
a class and from the information we provide there make choices about
which API/classes they want to employ.

Derek

On 6/26/06, Roy Stogner <roy...@ic...> wrote:
>
> It occurs to me that the task of packaging up stable releases while
> simultaneously adding and changing APIs might be easier if we had a
> way to set apart functions which are still "in flux".  Right now we
> could pull my experimental stuff out for 0.6.0, but I'd rather toss a
> call to "experimental();" into the class constructors - then users
> with the default compiler options would see a warning on std::cerr if
> they tried to use an object whose implementation might be buggy or
> whose interface might be changed.
>
> Similarly if we wanted to make a change into a stable API but couldn't
> make it without breaking old code (the change from component_mask to
> component_scale is what I'm thinking of here), we might keep the old
> API working side by side with the new for a release or two, but with a
> call to "deprecated();" that would warn most users on std::cerr.
>
> Any thoughts?  What I'd additionally like is to have some clear way of
> delineating "this is an API we're going to keep stable for our users"
> from "this is an internal API we may change freely", but I don't know
> how to do that.  In C you'd just put the internal APIs in their own
> header files in a separate directory, but in C++ you can't break up
> declarations of methods that act on the same class.
> ---
> Roy
>
> Using Tomcat but need to do more? Need to support web services, security?
> Get stuff done quickly with pre-integrated technology to make your job easier
> Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
> _______________________________________________
> Libmesh-devel mailing list
> Lib...@li...
> https://lists.sourceforge.net/lists/listinfo/libmesh-devel
>