general: mark deprecated methods with the @deprecated tag

rdb · rdb · commit 05ed918d6366 · 2019-09-08T09:50:28.000+02:00
This makes them easier to find and, if necessary, automatically generate deprecation warnings for.
diff --git a/panda/src/bullet/bulletWorld.cxx b/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) {
diff --git a/panda/src/char/character.cxx b/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() {
diff --git a/panda/src/collide/collisionHandlerEvent.I b/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) {
diff --git a/panda/src/display/graphicsOutput.cxx b/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) {
diff --git a/panda/src/distort/nonlinearImager.cxx b/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) {
diff --git a/panda/src/egg/eggPrimitive.I b/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::
diff --git a/panda/src/egg2pg/eggLoader.cxx b/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,
diff --git a/panda/src/event/eventQueue.cxx b/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 {
diff --git a/panda/src/linmath/lvector3_src.I b/panda/src/linmath/lvector3_src.I
@@ -230,15 +230,15 @@ 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 {
   return atan2((_v(0)*other._v(1))-(_v(1)*other._v(0)), dot(other));
 }
 
 /**
- * This method is deprecated.  Do not use.
+ * @deprecated Do not use.
  */
 INLINE_LINMATH FLOATTYPE FLOATNAME(LVector3)::
 relative_angle_deg(const FLOATNAME(LVector3) &other) const {
diff --git a/panda/src/pgraph/clipPlaneAttrib.cxx b/panda/src/pgraph/clipPlaneAttrib.cxx
@@ -45,8 +45,7 @@ class ComparePlaneNodePriorities {
  * 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()
- * instead.
+ * @deprecated Use add_on_plane() or add_off_plane() 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()
- * instead.
+ * @deprecated Use add_on_plane() or add_off_plane() 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()
- * instead.
+ * @deprecated Use add_on_plane() or add_off_plane() 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()
- * instead.
+ * @deprecated Use add_on_plane() or add_off_plane() 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
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
- * the lists independently.
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
+ * off_planes, so this method no longer makes sense.  Query the lists
+ * 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
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
- * the lists independently.
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
+ * off_planes, so this method no longer makes sense.  Query the lists
+ * 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
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
- * the lists independently.
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
+ * off_planes, so this method no longer makes sense.  Query the lists
+ * 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
- * list of on_planes and off_planes, so this method doesn't make sense.  Query
- * the lists independently.
+ * @deprecated ClipPlaneAttribs nowadays have a separate list of on_planes and
+ * off_planes, so this method no longer makes sense.  Query the lists
+ * 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()
- * instead.
+ * @deprecated Use add_on_plane() or add_off_plane() 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()
- * instead.
+ * @deprecated Use remove_on_plane() or remove_off_plane() instead.
  */
 CPT(RenderAttrib) ClipPlaneAttrib::
 remove_plane(PlaneNode *plane) const {
diff --git a/panda/src/pgraph/colorBlendAttrib.cxx b/panda/src/pgraph/colorBlendAttrib.cxx
@@ -35,8 +35,9 @@ make_off() {
 }
 
 /**
- * Constructs a new ColorBlendAttrib object.  This constructor is deprecated;
- * use the one below, which takes three or four parameters, instead.
+ * Constructs a new ColorBlendAttrib object.
+ *
+ * @deprecated Use the three- or four-parameter constructor instead.
  */
 CPT(RenderAttrib) ColorBlendAttrib::
 make(ColorBlendAttrib::Mode mode) {
diff --git a/panda/src/pgraph/lightAttrib.cxx b/panda/src/pgraph/lightAttrib.cxx
diff --git a/panda/src/pgraph/modelPool.I b/panda/src/pgraph/modelPool.I
diff --git a/panda/src/pgraph/texMatrixAttrib.cxx b/panda/src/pgraph/texMatrixAttrib.cxx

Original file line number	Diff line number	Diff line change
`@@ -81,7 +81,7 @@ is_queue_empty() const {`
`81`	`81`	`}`
`82`	`82`
`83`	`83`	`/**`
`84`		`- * This function is deprecated--the queue is never full these days.`
	`84`	`+ * @deprecated Always returns false; the queue can never be full.`
`85`	`85`	`*/`
`86`	`86`	`bool EventQueue::`
`87`	`87`	`is_queue_full() const {`