From ea46d76a2ebe245ff410c9c721553650ce919347 Mon Sep 17 00:00:00 2001
From: Zbynek Slajchrt <zbynek.slajchrt@oracle.com>
Date: Mon, 5 Dec 2016 16:48:44 +0100
Subject: [PATCH] JavaDoc added to attribute nodes
---
.../r/nodes/attributes/GetAttributeNode.java | 6 ++++++
.../attributes/GetFixedAttributeNode.java | 6 ++++++
.../r/nodes/attributes/SetAttributeNode.java | 10 ++++++++++
.../attributes/SetFixedAttributeNode.java | 10 ++++++++++
.../SpecialAttributesFunctions.java | 19 +++++++++++++++++++
5 files changed, 51 insertions(+)
diff --git a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetAttributeNode.java b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetAttributeNode.java
index a3d0c24731..27d4fd9012 100644
--- a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetAttributeNode.java
+++ b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetAttributeNode.java
@@ -32,6 +32,12 @@ import com.oracle.truffle.api.object.Shape;
import com.oracle.truffle.api.profiles.BranchProfile;
import com.oracle.truffle.r.runtime.data.RAttributable;
+/**
+ * This node is responsible for retrieving a value from an arbitrary attribute. It accepts both
+ * {@link DynamicObject} and {@link RAttributable} instances as the first argument. If the first
+ * argument is {@link RAttributable} and its attributes are initialized, the recursive instance of
+ * this class is used to get the attribute value from the attributes.
+ */
public abstract class GetAttributeNode extends AttributeAccessNode {
@Child private GetAttributeNode recursive;
diff --git a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetFixedAttributeNode.java b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetFixedAttributeNode.java
index 00044e606d..24910e4e0a 100644
--- a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetFixedAttributeNode.java
+++ b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/GetFixedAttributeNode.java
@@ -33,6 +33,12 @@ import com.oracle.truffle.api.profiles.BranchProfile;
import com.oracle.truffle.r.runtime.RRuntime;
import com.oracle.truffle.r.runtime.data.RAttributable;
+/**
+ * This node is responsible for retrieving a value from the predefined (fixed) attribute. It accepts
+ * both {@link DynamicObject} and {@link RAttributable} instances as the first argument. If the
+ * first argument is {@link RAttributable} and its attributes are initialized, the recursive
+ * instance of this class is used to get the attribute value from the attributes.
+ */
public abstract class GetFixedAttributeNode extends FixedAttributeAccessNode {
@Child private GetFixedAttributeNode recursive;
diff --git a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetAttributeNode.java b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetAttributeNode.java
index 2856f8b339..c09d2d58bc 100644
--- a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetAttributeNode.java
+++ b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetAttributeNode.java
@@ -35,6 +35,16 @@ import com.oracle.truffle.api.profiles.BranchProfile;
import com.oracle.truffle.r.runtime.RInternalError;
import com.oracle.truffle.r.runtime.data.RAttributable;
+/**
+ * This node is responsible for setting a value to an arbitrary attribute. It accepts both
+ * {@link DynamicObject} and {@link RAttributable} instances as the first argument. If the first
+ * argument is {@link RAttributable} and the attribute is a special one (i.e. names, dims, dimnames,
+ * rownames), a corresponding node defined in the {@link SpecialAttributesFunctions} class is
+ * created and the processing is delegated to it. If the first argument is {@link RAttributable} and
+ * the attribute is not a special one, it is made sure that the attributes in the first argument are
+ * initialized. Then the recursive instance of this class is used to set the attribute value to the
+ * attributes.
+ */
public abstract class SetAttributeNode extends AttributeAccessNode {
@Child SetAttributeNode recursive;
diff --git a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetFixedAttributeNode.java b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetFixedAttributeNode.java
index e427dc9cb4..b50ffbabe5 100644
--- a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetFixedAttributeNode.java
+++ b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SetFixedAttributeNode.java
@@ -37,6 +37,16 @@ import com.oracle.truffle.r.runtime.RInternalError;
import com.oracle.truffle.r.runtime.RRuntime;
import com.oracle.truffle.r.runtime.data.RAttributable;
+/**
+ * This node is responsible for setting a value to the predefined (fixed) attribute. It accepts both
+ * {@link DynamicObject} and {@link RAttributable} instances as the first argument. If the first
+ * argument is {@link RAttributable} and the attribute is a special one (i.e. names, dims, dimnames,
+ * rownames), a corresponding node defined in the {@link SpecialAttributesFunctions} class is
+ * created and the processing is delegated to it. If the first argument is {@link RAttributable} and
+ * the attribute is not a special one, it is made sure that the attributes in the first argument are
+ * initialized. Then the recursive instance of this class is used to set the attribute value to the
+ * attributes.
+ */
public abstract class SetFixedAttributeNode extends FixedAttributeAccessNode {
@Child private SetFixedAttributeNode recursive;
diff --git a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SpecialAttributesFunctions.java b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SpecialAttributesFunctions.java
index fa9375895a..3fe2f477a3 100644
--- a/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SpecialAttributesFunctions.java
+++ b/com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/attributes/SpecialAttributesFunctions.java
@@ -43,8 +43,15 @@ import com.oracle.truffle.r.runtime.data.model.RAbstractIntVector;
import com.oracle.truffle.r.runtime.data.model.RAbstractVector;
import com.oracle.truffle.r.runtime.nodes.RBaseNode;
+/**
+ * This class defines a number of nodes used to handle the special attributes, such as names, dims,
+ * dimnames and rownames.
+ */
public final class SpecialAttributesFunctions {
+ /**
+ * A node used in guards, for example, to determine whether an attribute is a special one.
+ */
public static final class IsSpecialAttributeNode extends RBaseNode {
private final BranchProfile namesProfile = BranchProfile.create();
@@ -95,6 +102,9 @@ public final class SpecialAttributesFunctions {
}
}
+ /**
+ * A node for setting a value to any special attribute.
+ */
public static final class GenericSpecialAttributeNode extends RBaseNode {
private final BranchProfile namesProfile = BranchProfile.create();
@@ -151,6 +161,12 @@ public final class SpecialAttributesFunctions {
}
}
+ /**
+ * A factory method for creating a node handling the given special attribute.
+ *
+ * @param name the special attribute name
+ * @return the node
+ */
public static SetSpecialAttributeNode createSpecialAttributeNode(String name) {
assert name.intern() == name;
if (name == RRuntime.NAMES_ATTR_KEY) {
@@ -168,6 +184,9 @@ public final class SpecialAttributesFunctions {
}
}
+ /**
+ * The base class for the nodes setting values to special attributes.
+ */
public abstract static class SetSpecialAttributeNode extends RBaseNode {
public abstract void execute(RAttributable x, Object attrValue);
--
GitLab