general: mark deprecated methods with the @deprecated tag

This makes them easier to find and, if necessary, automatically generate deprecation warnings for.

panda/src/bullet/bulletWorld.cxx

@@ -363,7 +363,7 @@ remove(TypedObject *object) {
 }
 
 /**
- * Deprecated!  Please use BulletWorld::attach
+ * @deprecated Please use BulletWorld::attach
  */
 void BulletWorld::
 attach_rigid_body(BulletRigidBodyNode *node) {
@@ -373,7 +373,7 @@ attach_rigid_body(BulletRigidBodyNode *node) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_rigid_body(BulletRigidBodyNode *node) {
@@ -383,7 +383,7 @@ remove_rigid_body(BulletRigidBodyNode *node) {
 }
 
 /**
- * Deprecated!  Please use BulletWorld::attach
+ * @deprecated Please use BulletWorld::attach
  */
 void BulletWorld::
 attach_soft_body(BulletSoftBodyNode *node) {
@@ -393,7 +393,7 @@ attach_soft_body(BulletSoftBodyNode *node) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_soft_body(BulletSoftBodyNode *node) {
@@ -403,7 +403,7 @@ remove_soft_body(BulletSoftBodyNode *node) {
 }
 
 /**
- * Deprecated!  Please use BulletWorld::attach
+ * @deprecated Please use BulletWorld::attach
  */
 void BulletWorld::
 attach_ghost(BulletGhostNode *node) {
@@ -413,7 +413,7 @@ attach_ghost(BulletGhostNode *node) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_ghost(BulletGhostNode *node) {
@@ -423,7 +423,7 @@ remove_ghost(BulletGhostNode *node) {
 }
 
 /**
- * Deprecated!  Please use BulletWorld::attach
+ * @deprecated Please use BulletWorld::attach
  */
 void BulletWorld::
 attach_character(BulletBaseCharacterControllerNode *node) {
@@ -433,7 +433,7 @@ attach_character(BulletBaseCharacterControllerNode *node) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_character(BulletBaseCharacterControllerNode *node) {
@@ -443,7 +443,7 @@ remove_character(BulletBaseCharacterControllerNode *node) {
 }
 
 /**
- * Deprecated!  Please use BulletWorld::attach
+ * @deprecated Please use BulletWorld::attach
  */
 void BulletWorld::
 attach_vehicle(BulletVehicle *vehicle) {
@@ -453,7 +453,7 @@ attach_vehicle(BulletVehicle *vehicle) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_vehicle(BulletVehicle *vehicle) {
@@ -474,7 +474,7 @@ attach_constraint(BulletConstraint *constraint, bool linked_collision) {
 }
 
 /**
- * Deprecated.! Please use BulletWorld::remove
+ * @deprecated Please use BulletWorld::remove
  */
 void BulletWorld::
 remove_constraint(BulletConstraint *constraint) {

panda/src/char/character.cxx

@@ -243,7 +243,7 @@ calc_tight_bounds(LPoint3 &min_point, LPoint3 &max_point, bool &found_any,
  * pointer within this node will be replaced with the new_bundle pointer, and
  * all geometry within this node will be updated to reference new_bundle.
  *
- * This method is deprecated.  Use the newer version of this method, below.
+ * @deprecated Use the newer version of this method, below.
  */
 void Character::
 merge_bundles(PartBundle *old_bundle, PartBundle *new_bundle) {
@@ -417,7 +417,7 @@ write_part_values(std::ostream &out) const {
  * character's position to the current frame, regardless of whether the
  * character is currently onscreen and animating.
  *
- * This method is deprecated.  Call update() instead.
+ * @deprecated Call update() instead.
  */
 void Character::
 update_to_now() {

panda/src/collide/collisionHandlerEvent.I

@@ -80,6 +80,8 @@ add_in_pattern(const std::string &in_pattern) {
 /**
  * This method is deprecated; it completely replaces all the in patterns that
  * have previously been set with the indicated pattern.
+ *
+ * @deprecated Use add_in_pattern() instead.
  */
 INLINE void CollisionHandlerEvent::
 set_in_pattern(const std::string &in_pattern) {
@@ -133,6 +135,8 @@ add_again_pattern(const std::string &again_pattern) {
 /**
  * This method is deprecated; it completely replaces all the in patterns that
  * have previously been set with the indicated pattern.
+ *
+ * @deprecated Use add_again_pattern() instead.
  */
 INLINE void CollisionHandlerEvent::
 set_again_pattern(const std::string &again_pattern) {
@@ -184,6 +188,8 @@ add_out_pattern(const std::string &out_pattern) {
 /**
  * This method is deprecated; it completely replaces all the in patterns that
  * have previously been set with the indicated pattern.
+ *
+ * @deprecated Use add_out_pattern() instead.
  */
 INLINE void CollisionHandlerEvent::
 set_out_pattern(const std::string &out_pattern) {

panda/src/display/graphicsOutput.cxx

@@ -375,6 +375,8 @@ add_render_texture(Texture *tex, RenderTextureMode mode,
  * This is a deprecated interface that made sense back when GraphicsOutputs
  * could only render into one texture at a time.  From now on, use
  * clear_render_textures and add_render_texture instead.
+ *
+ * @deprecated Use add_render_texture() instead.
  */
 void GraphicsOutput::
 setup_render_texture(Texture *tex, bool allow_bind, bool to_ram) {

panda/src/distort/nonlinearImager.cxx

@@ -49,6 +49,8 @@ NonlinearImager::
 /**
  * This version of this method is deprecated and will soon be removed.  Use
  * the version that takes two parameters instead.
+ *
+ * @deprecated Use the version that takes two parameters instead.
  */
 int NonlinearImager::
 add_screen(ProjectionScreen *screen) {

panda/src/egg/eggPrimitive.I

@@ -109,7 +109,7 @@ get_connected_shading() const {
 /**
  * Replaces the current list of textures with the indicated texture.
  *
- * This method is deprecated and is used in support of single-texturing only.
+ * @deprecated This method is used in support of single-texturing only.
  * Please use the multitexture variant add_texture instead.
  */
 INLINE void EggPrimitive::
@@ -121,7 +121,7 @@ set_texture(EggTexture *texture) {
 /**
  * Returns true if the primitive has any textures specified, false otherwise.
  *
- * This method is deprecated and is used in support of single-texturing only.
+ * @deprecated This method is used in support of single-texturing only.
  * New code should be written to use the multitexture variants instead.
  */
 INLINE bool EggPrimitive::
@@ -143,7 +143,7 @@ has_texture(EggTexture *texture) const {
  * Returns the first texture on the primitive, if any, or NULL if there are no
  * textures on the primitive.
  *
- * This method is deprecated and is used in support of single-texturing only.
+ * @deprecated This method is used in support of single-texturing only.
  * New code should be written to use the multitexture variants instead.
  */
 INLINE EggTexture *EggPrimitive::

panda/src/egg2pg/eggLoader.cxx

@@ -726,6 +726,8 @@ make_nurbs_curve(EggNurbsCurve *egg_curve, PandaNode *parent,
  * This deprecated interface creates a NurbsCurve object for the EggNurbsCurve
  * entry.  It will eventually be removed in favor of the above, which creates
  * a RopeNode.
+ *
+ * @deprecated See make_nurbs_curve.
  */
 void EggLoader::
 make_old_nurbs_curve(EggNurbsCurve *egg_curve, PandaNode *parent,

panda/src/event/eventQueue.cxx

@@ -81,7 +81,7 @@ is_queue_empty() const {
 }
 
 /**
- * This function is deprecated--the queue is never full these days.
+ * @deprecated Always returns false; the queue can never be full.
  */
 bool EventQueue::
 is_queue_full() const {

panda/src/linmath/lvector3_src.I

@@ -230,7 +230,7 @@ signed_angle_deg(const FLOATNAME(LVector3) &other,
 }
 
 /**
- * This method is deprecated.  Do not use.
+ * @deprecated Do not use.
  */
 INLINE_LINMATH FLOATTYPE FLOATNAME(LVector3)::
 relative_angle_rad(const FLOATNAME(LVector3) &other) const {
@@ -238,7 +238,7 @@ relative_angle_rad(const FLOATNAME(LVector3) &other) const {
 }
 
 /**
- * This method is deprecated.  Do not use.
+ * @deprecated Do not use.
  */
 INLINE_LINMATH FLOATTYPE FLOATNAME(LVector3)::
 relative_angle_deg(const FLOATNAME(LVector3) &other) const {

panda/src/pgraph/clipPlaneAttrib.cxx

@@ -45,8 +45,7 @@ public:
  * Constructs a new ClipPlaneAttrib object that enables (or disables,
  * according to op) the indicated plane(s).
  *
- * This method is now deprecated.  Use add_on_plane() or add_off_plane()
+ * @deprecated Use add_on_plane() or add_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 make(ClipPlaneAttrib::Operation op, PlaneNode *plane) {
@@ -80,8 +79,7 @@ make(ClipPlaneAttrib::Operation op, PlaneNode *plane) {
  * Constructs a new ClipPlaneAttrib object that turns on (or off, according to
  * op) the indicate plane(s).
  *
- * This method is now deprecated.  Use add_on_plane() or add_off_plane()
+ * @deprecated Use add_on_plane() or add_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 make(ClipPlaneAttrib::Operation op, PlaneNode *plane1, PlaneNode *plane2) {
@@ -118,8 +116,7 @@ make(ClipPlaneAttrib::Operation op, PlaneNode *plane1, PlaneNode *plane2) {
  * Constructs a new ClipPlaneAttrib object that turns on (or off, according to
  * op) the indicate plane(s).
  *
- * This method is now deprecated.  Use add_on_plane() or add_off_plane()
+ * @deprecated Use add_on_plane() or add_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 make(ClipPlaneAttrib::Operation op, PlaneNode *plane1, PlaneNode *plane2,
@@ -160,8 +157,7 @@ make(ClipPlaneAttrib::Operation op, PlaneNode *plane1, PlaneNode *plane2,
  * Constructs a new ClipPlaneAttrib object that turns on (or off, according to
  * op) the indicate plane(s).
  *
- * This method is now deprecated.  Use add_on_plane() or add_off_plane()
+ * @deprecated Use add_on_plane() or add_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 make(ClipPlaneAttrib::Operation op, PlaneNode *plane1, PlaneNode *plane2,
@@ -217,9 +213,9 @@ make_default() {
  * were already on, and if O_remove, the planes here are removed from the set
  * of planes that were on.
  *
- * This method is now deprecated.  ClipPlaneAttribs nowadays have a separate
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
+ * off_planes, so this method no longer makes sense.  Query the lists
- * the lists independently.
+ * independently.
  */
 ClipPlaneAttrib::Operation ClipPlaneAttrib::
 get_operation() const {
@@ -240,9 +236,9 @@ get_operation() const {
 /**
  * Returns the number of planes listed in the attribute.
  *
- * This method is now deprecated.  ClipPlaneAttribs nowadays have a separate
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
+ * off_planes, so this method no longer makes sense.  Query the lists
- * the lists independently.
+ * independently.
  */
 int ClipPlaneAttrib::
 get_num_planes() const {
@@ -259,9 +255,9 @@ get_num_planes() const {
 /**
  * Returns the nth plane listed in the attribute.
  *
- * This method is now deprecated.  ClipPlaneAttribs nowadays have a separate
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
+ * off_planes, so this method no longer makes sense.  Query the lists
- * the lists independently.
+ * independently.
  */
 PlaneNode *ClipPlaneAttrib::
 get_plane(int n) const {
@@ -279,9 +275,9 @@ get_plane(int n) const {
  * Returns true if the indicated plane is listed in the attrib, false
  * otherwise.
  *
- * This method is now deprecated.  ClipPlaneAttribs nowadays have a separate
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
+ * off_planes, so this method no longer makes sense.  Query the lists
- * the lists independently.
+ * independently.
  */
 bool ClipPlaneAttrib::
 has_plane(PlaneNode *plane) const {
@@ -299,8 +295,7 @@ has_plane(PlaneNode *plane) const {
  * Returns a new ClipPlaneAttrib, just like this one, but with the indicated
  * plane added to the list of planes.
  *
- * This method is now deprecated.  Use add_on_plane() or add_off_plane()
+ * @deprecated Use add_on_plane() or add_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 add_plane(PlaneNode *plane) const {
@@ -318,8 +313,7 @@ add_plane(PlaneNode *plane) const {
  * Returns a new ClipPlaneAttrib, just like this one, but with the indicated
  * plane removed from the list of planes.
  *
- * This method is now deprecated.  Use remove_on_plane() or remove_off_plane()
+ * @deprecated Use remove_on_plane() or remove_off_plane() instead.
- * instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 remove_plane(PlaneNode *plane) const {

panda/src/pgraph/colorBlendAttrib.cxx

@@ -35,8 +35,9 @@ make_off() {
 }
 
 /**
- * Constructs a new ColorBlendAttrib object.  This constructor is deprecated;
+ * Constructs a new ColorBlendAttrib object.
- * use the one below, which takes three or four parameters, instead.
+ *
+ * @deprecated Use the three- or four-parameter constructor instead.
  */
 CPT(RenderAttrib) ColorBlendAttrib::
 make(ColorBlendAttrib::Mode mode) {

panda/src/pgraph/lightAttrib.cxx

@@ -89,8 +89,7 @@ LightAttrib::
  * Constructs a new LightAttrib object that turns on (or off, according to op)
  * the indicated light(s).
  *
- * This method is now deprecated.  Use add_on_light() or add_off_light()
+ * @deprecated Use add_on_light() or add_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 make(LightAttrib::Operation op, Light *light) {
@@ -124,8 +123,7 @@ make(LightAttrib::Operation op, Light *light) {
  * Constructs a new LightAttrib object that turns on (or off, according to op)
  * the indicate light(s).
  *
- * This method is now deprecated.  Use add_on_light() or add_off_light()
+ * @deprecated Use add_on_light() or add_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 make(LightAttrib::Operation op, Light *light1, Light *light2) {
@@ -162,8 +160,7 @@ make(LightAttrib::Operation op, Light *light1, Light *light2) {
  * Constructs a new LightAttrib object that turns on (or off, according to op)
  * the indicate light(s).
  *
- * This method is now deprecated.  Use add_on_light() or add_off_light()
+ * @deprecated Use add_on_light() or add_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 make(LightAttrib::Operation op, Light *light1, Light *light2,
@@ -204,8 +201,7 @@ make(LightAttrib::Operation op, Light *light1, Light *light2,
  * Constructs a new LightAttrib object that turns on (or off, according to op)
  * the indicate light(s).
  *
- * This method is now deprecated.  Use add_on_light() or add_off_light()
+ * @deprecated Use add_on_light() or add_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 make(LightAttrib::Operation op, Light *light1, Light *light2,
@@ -261,9 +257,9 @@ make_default() {
  * already on, and if O_remove, the lights here are removed from the set of
  * lights that were on.
  *
- * This method is now deprecated.  LightAttribs nowadays have a separate list
+ * @deprecated LightAttribs nowadays have a separate list of on_lights and
- * of on_lights and off_lights, so this method doesn't make sense.  Query the
+ * off_lights, so this method no longer makes sense.  Query the lists
- * lists independently.
+ * independently.
  */
 LightAttrib::Operation LightAttrib::
 get_operation() const {
@@ -284,9 +280,9 @@ get_operation() const {
 /**
  * Returns the number of lights listed in the attribute.
  *
- * This method is now deprecated.  LightAttribs nowadays have a separate list
+ * @deprecated LightAttribs nowadays have a separate list of on_lights and
- * of on_lights and off_lights, so this method doesn't make sense.  Query the
+ * off_lights, so this method no longer makes sense.  Query the lists
- * lists independently.
+ * independently.
  */
 int LightAttrib::
 get_num_lights() const {
@@ -303,9 +299,9 @@ get_num_lights() const {
 /**
  * Returns the nth light listed in the attribute.
  *
- * This method is now deprecated.  LightAttribs nowadays have a separate list
+ * @deprecated LightAttribs nowadays have a separate list of on_lights and
- * of on_lights and off_lights, so this method doesn't make sense.  Query the
+ * off_lights, so this method no longer makes sense.  Query the lists
- * lists independently.
+ * independently.
  */
 Light *LightAttrib::
 get_light(int n) const {
@@ -323,9 +319,9 @@ get_light(int n) const {
  * Returns true if the indicated light is listed in the attrib, false
  * otherwise.
  *
- * This method is now deprecated.  LightAttribs nowadays have a separate list
+ * @deprecated LightAttribs nowadays have a separate list of on_lights and
- * of on_lights and off_lights, so this method doesn't make sense.  Query the
+ * off_lights, so this method no longer makes sense.  Query the lists
- * lists independently.
+ * independently.
  */
 bool LightAttrib::
 has_light(Light *light) const {
@@ -343,8 +339,7 @@ has_light(Light *light) const {
  * Returns a new LightAttrib, just like this one, but with the indicated light
  * added to the list of lights.
  *
- * This method is now deprecated.  Use add_on_light() or add_off_light()
+ * @deprecated Use add_on_light() or add_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 add_light(Light *light) const {
@@ -362,8 +357,7 @@ add_light(Light *light) const {
  * Returns a new LightAttrib, just like this one, but with the indicated light
  * removed from the list of lights.
  *
- * This method is now deprecated.  Use remove_on_light() or remove_off_light()
+ * @deprecated Use remove_on_light() or remove_off_light() instead.
- * instead.
  */
 CPT(RenderAttrib) LightAttrib::
 remove_light(Light *light) const {

panda/src/pgraph/modelPool.I

@@ -63,8 +63,7 @@ load_model(const Filename &filename, const LoaderOptions &options) {
  * Adds the indicated already-loaded model to the pool.  The model will
  * replace any previously-loaded model in the pool that had the same filename.
  *
- * This two-parameter version of this method is deprecated; use the one-
+ * @deprecated Use the one-parameter add_model(model) instead.
- * parameter add_model(model) instead.
  */
 INLINE void ModelPool::
 add_model(const Filename &filename, ModelRoot *model) {
@@ -77,8 +76,7 @@ add_model(const Filename &filename, ModelRoot *model) {
  * called, a reference count will be maintained on every model every loaded,
  * and models will never be freed.
  *
- * This version of this method is deprecated; use release_model(model)
+ * @deprecated Use release_model(model) instead.
- * instead.
  */
 INLINE void ModelPool::
 release_model(const Filename &filename) {

panda/src/pgraph/texMatrixAttrib.cxx

@@ -48,6 +48,8 @@ make() {
 /**
  * Constructs a TexMatrixAttrib that applies the indicated matrix to the
  * default texture stage.  This interface is deprecated.
+ *
+ * @deprecated Use the constructor that takes a TextureStage instead.
  */
 CPT(RenderAttrib) TexMatrixAttrib::
 make(const LMatrix4 &mat) {