Mark the deprecated AS API bindings in the documentation.

Also print a warning when it is being used in the script.

Source/Engine/LuaScript/pkgs/Resource/Resource.pkg

@@ -24,10 +24,7 @@ static bool ResourceLoad(Resource* resource, const String& fileName)
         return false;
 
     File file(resource->GetContext());
-    if (!file.Open(fileName, FILE_READ))
-        return false;
-
-    return resource->Load(file);
+    return file.Open(fileName, FILE_READ) && resource->Load(file);
 }
 
 static bool ResourceSave(const Resource* resource, const String& fileName)
@@ -36,9 +33,6 @@ static bool ResourceSave(const Resource* resource, const String& fileName)
         return false;
 
     File file(resource->GetContext());
-    if (!file.Open(fileName, FILE_WRITE))
-        return false;
-
-    return resource->Save(file);
+    return file.Open(fileName, FILE_WRITE) && resource->Save(file);
 }
-$}
+$}

Source/Engine/Script/APITemplates.h

@@ -28,6 +28,7 @@
 #include "Drawable.h"
 #include "File.h"
 #include "HashSet.h"
+#include "Log.h"
 #include "Node.h"
 #include "Renderer.h"
 #include "Resource.h"
@@ -54,8 +55,10 @@ template <class T, class U> U* RefCast(T* t)
 }
 
 /// Template function for returning a Variant pointer type cast to specific class.
-template <class T> T* GetVariantPtr(Variant* ptr)
+template <class T> T* GetVariantPtr(const String& binding, Variant* ptr)
 {
+    LOGWARNINGF("The %s API binding is deprecated, GetPtr() should be used instead.", binding.Substring(11).CString());
+
     if (ptr->GetType() == VAR_PTR)
         return dynamic_cast<T*>(ptr->GetPtr());
     else if (ptr->GetType() == VAR_VOIDPTR)

Source/Engine/Script/GraphicsAPI.cpp

@@ -120,7 +120,7 @@ static void RegisterCamera(asIScriptEngine* engine)
     engine->RegisterObjectMethod("Camera", "Matrix3x4 get_effectiveWorldTransform() const", asMETHOD(Camera, GetEffectiveWorldTransform), asCALL_THISCALL);
 
     // Register Variant GetPtr() for Camera. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "Camera@+ GetCamera() const", asFUNCTION(GetVariantPtr<Camera>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Camera@+ GetCamera(const String&in binding = \"deprecated:GetCamera\") const", asFUNCTION(GetVariantPtr<Camera>), asCALL_CDECL_OBJLAST);
 }
 
 static Node* BoneGetNode(Bone* ptr)
@@ -446,7 +446,7 @@ static void RegisterTextures(asIScriptEngine* engine)
     engine->RegisterObjectMethod("RenderSurface", "RenderSurface@+ get_linkedDepthStencil() const", asMETHOD(RenderSurface, GetLinkedDepthStencil), asCALL_THISCALL);
     
     // Register Variant GetPtr() for RenderSurface. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "RenderSurface@+ GetRenderSurface() const", asFUNCTION(GetVariantPtr<RenderSurface>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "RenderSurface@+ GetRenderSurface(const String&in binding = \"deprecated:GetRenderSurface\") const", asFUNCTION(GetVariantPtr<RenderSurface>), asCALL_CDECL_OBJLAST);
     
     RegisterTexture<Texture2D>(engine, "Texture2D");
     engine->RegisterObjectMethod("Texture2D", "bool SetSize(int, int, uint, TextureUsage usage = TEXTURE_STATIC)", asMETHOD(Texture2D, SetSize), asCALL_THISCALL);
@@ -464,7 +464,7 @@ static void RegisterTextures(asIScriptEngine* engine)
     engine->RegisterObjectMethod("TextureCube", "RenderSurface@+ get_renderSurfaces(CubeMapFace) const", asMETHOD(TextureCube, GetRenderSurface), asCALL_THISCALL);
     
     // Register Variant GetPtr() for Texture. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "Texture@+ GetTexture() const", asFUNCTION(GetVariantPtr<Texture>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Texture@+ GetTexture(const String&in binding = \"deprecated:GetTexture\") const", asFUNCTION(GetVariantPtr<Texture>), asCALL_CDECL_OBJLAST);
     
     engine->RegisterGlobalFunction("uint GetAlphaFormat()", asFUNCTION(Graphics::GetAlphaFormat), asCALL_CDECL);
     engine->RegisterGlobalFunction("uint GetLuminanceFormat()", asFUNCTION(Graphics::GetLuminanceFormat), asCALL_CDECL);

Source/Engine/Script/NetworkAPI.cpp

@@ -112,7 +112,7 @@ static void RegisterConnection(asIScriptEngine* engine)
     engine->RegisterObjectProperty("Connection", "VariantMap identity", offsetof(Connection, identity_));
     
     // Register Variant GetPtr() for Connection. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "Connection@+ GetConnection() const", asFUNCTION(GetVariantPtr<Connection>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Connection@+ GetConnection(const String&in binding = \"deprecated:GetConnection\") const", asFUNCTION(GetVariantPtr<Connection>), asCALL_CDECL_OBJLAST);
     
     // Register SetOwner/GetOwner now
     engine->RegisterObjectMethod("Node", "void set_owner(Connection@+)", asMETHOD(Node, SetOwner), asCALL_THISCALL);

Source/Engine/Script/PhysicsAPI.cpp

@@ -102,7 +102,7 @@ static void RegisterCollisionShape(asIScriptEngine* engine)
     engine->RegisterObjectMethod("CollisionShape", "BoundingBox get_worldBoundingBox() const", asMETHOD(CollisionShape, GetWorldBoundingBox), asCALL_THISCALL);
     
     // Register Variant GetPtr() for CollisionShape. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "CollisionShape@+ GetCollisionShape() const", asFUNCTION(GetVariantPtr<CollisionShape>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "CollisionShape@+ GetCollisionShape(const String&in binding = \"deprecated:GetCollisionShape\") const", asFUNCTION(GetVariantPtr<CollisionShape>), asCALL_CDECL_OBJLAST);
 }
 
 static CScriptArray* RigidBodyGetCollidingBodies(RigidBody* ptr)
@@ -187,7 +187,7 @@ static void RegisterRigidBody(asIScriptEngine* engine)
     engine->RegisterObjectMethod("RigidBody", "Array<RigidBody@>@ get_collidingBodies() const", asFUNCTION(RigidBodyGetCollidingBodies), asCALL_CDECL_OBJLAST);
 
     // Register Variant GetPtr() for RigidBody. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "RigidBody@+ GetRigidBody() const", asFUNCTION(GetVariantPtr<RigidBody>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "RigidBody@+ GetRigidBody(const String&in binding = \"deprecated:GetRigidBody\") const", asFUNCTION(GetVariantPtr<RigidBody>), asCALL_CDECL_OBJLAST);
 }
 
 static void RegisterConstraint(asIScriptEngine* engine)
@@ -308,7 +308,7 @@ static void RegisterPhysicsWorld(asIScriptEngine* engine)
     engine->RegisterGlobalFunction("PhysicsWorld@+ get_physicsWorld()", asFUNCTION(GetPhysicsWorld), asCALL_CDECL);
     
     // Register Variant GetPtr() for PhysicsWorld. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "PhysicsWorld@+ GetPhysicsWorld() const", asFUNCTION(GetVariantPtr<PhysicsWorld>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "PhysicsWorld@+ GetPhysicsWorld(const String&in binding = \"deprecated:GetPhysicWorld\") const", asFUNCTION(GetVariantPtr<PhysicsWorld>), asCALL_CDECL_OBJLAST);
 }
 
 void RegisterPhysicsAPI(asIScriptEngine* engine)

Source/Engine/Script/SceneAPI.cpp

@@ -75,9 +75,9 @@ static void RegisterNode(asIScriptEngine* engine)
     engine->RegisterObjectMethod("Component", "Node@+ get_node() const", asMETHOD(Component, GetNode), asCALL_THISCALL);
 
     // Register Variant GetPtr() for Serializable, Node & Component. These are deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "Serializable@+ GetSerializable() const", asFUNCTION(GetVariantPtr<Serializable>), asCALL_CDECL_OBJLAST);
-    engine->RegisterObjectMethod("Variant", "Node@+ GetNode() const", asFUNCTION(GetVariantPtr<Node>), asCALL_CDECL_OBJLAST);
-    engine->RegisterObjectMethod("Variant", "Component@+ GetComponent() const", asFUNCTION(GetVariantPtr<Component>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Serializable@+ GetSerializable(const String&in binding = \"deprecated:GetSerializable\") const", asFUNCTION(GetVariantPtr<Serializable>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Node@+ GetNode(const String&in binding = \"deprecated:GetNode\") const", asFUNCTION(GetVariantPtr<Node>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Component@+ GetComponent(const String&in binding = \"deprecated:GetComponent\") const", asFUNCTION(GetVariantPtr<Component>), asCALL_CDECL_OBJLAST);
 }
 
 static bool SceneLoadXML(File* file, Scene* ptr)
@@ -219,7 +219,7 @@ static void RegisterScene(asIScriptEngine* engine)
     engine->RegisterGlobalFunction("Scene@+ get_scene()", asFUNCTION(GetScriptContextScene), asCALL_CDECL);
 
     // Register Variant GetPtr() for Scene. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "Scene@+ GetScene() const", asFUNCTION(GetVariantPtr<Scene>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "Scene@+ GetScene(const String&in binding = \"deprecated:GetScene\") const", asFUNCTION(GetVariantPtr<Scene>), asCALL_CDECL_OBJLAST);
 
     engine->RegisterGlobalFunction("Array<String>@ GetObjectCategories()", asFUNCTION(GetObjectCategories), asCALL_CDECL);
     engine->RegisterGlobalFunction("Array<String>@ GetObjectsByCategory(const String&in)", asFUNCTION(GetObjectsByCategory), asCALL_CDECL);

Source/Engine/Script/Script.cpp

@@ -331,6 +331,18 @@ void Script::DumpAPI(DumpMode mode)
                     {
                         String prefix(typeName + "::");
                         declaration.Replace(prefix, "");
+                        ///\todo Is there a better way to mark deprecated API bindings for AngelScript?
+                        unsigned pos = declaration.FindLast("const String&in = \"deprecated:");
+                        if (pos != String::NPOS)
+                        {
+                            // Assume this 'mark' is added as the last parameter
+                            unsigned posEnd = declaration.Find(')', pos);
+                            if (pos != String::NPOS)
+                            {
+                                declaration.Replace(pos, posEnd - pos, "");
+                                declaration += "    // deprecated";
+                            }
+                        }
                         methodDeclarations.Push(declaration);
                     }
                 }
@@ -378,9 +390,9 @@ void Script::DumpAPI(DumpMode mode)
                     String remark;
                     String cppdoc;
                     if (!propertyInfos[j].write_)
-                        remark = " (readonly)";
+                        remark = "    // readonly";
                     else if (!propertyInfos[j].read_)
-                        remark = " (writeonly)";
+                        remark = "    // writeonly";
                     if (mode == C_HEADER && !remark.Empty())
                     {
                         cppdoc = "/*" + remark + " */\n";

Source/Engine/Script/UIAPI.cpp

@@ -106,7 +106,7 @@ static void RegisterUIElement(asIScriptEngine* engine)
     RegisterUIElement<UIElement>(engine, "UIElement");
 
     // Register Variant GetPtr() for UIElement. This is deprecated, GetPtr() should be used instead.
-    engine->RegisterObjectMethod("Variant", "UIElement@+ GetUIElement() const", asFUNCTION(GetVariantPtr<UIElement>), asCALL_CDECL_OBJLAST);
+    engine->RegisterObjectMethod("Variant", "UIElement@+ GetUIElement(const String&in binding = \"deprecated:GetUIElement\") const", asFUNCTION(GetVariantPtr<UIElement>), asCALL_CDECL_OBJLAST);
 }
 
 static void RegisterBorderImage(asIScriptEngine* engine)