Skip to content
This repository
Browse code

Added documentation to IronJS.Runtime in general and for ArgumentsObj…

…ect.cs specificallly.
  • Loading branch information...
commit 4ac68b942809f5d09b7782e0d5d71335bc6d257d 1 parent cf52365
Asbjørn Ulsberg authored September 09, 2011
2  Src/IronJS.Runtime/IronJS.Runtime.csproj
@@ -21,6 +21,7 @@
21 21
     <DefineConstants>DEBUG;TRACE</DefineConstants>
22 22
     <ErrorReport>prompt</ErrorReport>
23 23
     <WarningLevel>4</WarningLevel>
  24
+    <DocumentationFile>bin\Debug\IronJS.Runtime.xml</DocumentationFile>
24 25
   </PropertyGroup>
25 26
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
26 27
     <DebugType>pdbonly</DebugType>
@@ -29,6 +30,7 @@
29 30
     <DefineConstants>TRACE</DefineConstants>
30 31
     <ErrorReport>prompt</ErrorReport>
31 32
     <WarningLevel>4</WarningLevel>
  33
+    <DocumentationFile>bin\Release\IronJS.Runtime.xml</DocumentationFile>
32 34
   </PropertyGroup>
33 35
   <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|x86'">
34 36
     <DebugSymbols>true</DebugSymbols>
275  Src/IronJS.Runtime/Objects/ArgumentsObject.cs
... ...
@@ -1,19 +1,25 @@
1 1
 using System;
2  
-using System.Collections.Generic;
3 2
 using System.Linq;
4  
-using System.Text;
5 3
 
6 4
 namespace IronJS.Runtime
7 5
 {
8 6
     using ArgLink = Tuple<ParameterStorageType, int>;
9 7
 
  8
+    /// <summary>
  9
+    /// A <see cref="CommonObject"/> used as an argument to a <see cref="FunctionObject"/>.
  10
+    /// </summary>
10 11
     public class ArgumentsObject : CommonObject
11 12
     {
12  
-        public BoxedValue[] PrivateScope;
13  
-        public BoxedValue[] SharedScope;
14  
-        public ArgLink[] LinkMap;
15  
-        public bool LinkIntact = true;
  13
+        private bool linkIntact = true;
16 14
 
  15
+
  16
+        /// <summary>
  17
+        /// Initializes a new instance of the <see cref="ArgumentsObject"/> class.
  18
+        /// </summary>
  19
+        /// <param name="env">The environment.</param>
  20
+        /// <param name="linkMap">The link map.</param>
  21
+        /// <param name="privateScope">The private scope.</param>
  22
+        /// <param name="sharedScope">The shared scope.</param>
17 23
         public ArgumentsObject(
18 24
             Environment env,
19 25
             ArgLink[] linkMap,
@@ -26,45 +32,68 @@ public class ArgumentsObject : CommonObject
26 32
             LinkMap = linkMap;
27 33
         }
28 34
 
29  
-        public static ArgumentsObject CreateForVariadicFunction(
30  
-            FunctionObject f,
31  
-            BoxedValue[] privateScope,
32  
-            BoxedValue[] sharedScope,
33  
-            BoxedValue[] variadicArgs)
  35
+
  36
+        /// <summary>
  37
+        /// Gets or sets a value indicating whether to keep the link intact.
  38
+        /// </summary>
  39
+        /// <value>
  40
+        ///   <c>true</c> to keep the link intact; otherwise, <c>false</c>.
  41
+        /// </value>
  42
+        public bool LinkIntact
34 43
         {
35  
-            var x =
36  
-                new ArgumentsObject(
37  
-                    f.Env,
38  
-                    f.MetaData.ParameterStorage,
39  
-                    privateScope,
40  
-                    sharedScope
41  
-                );
  44
+            get { return this.linkIntact; }
  45
+            set { this.linkIntact = value; }
  46
+        }
42 47
 
43  
-            x.CopyLinkedValues();
44  
-            x.Put("constructor", f.Env.Constructors.Object, (uint)0xffffff08);
45  
-            x.Put("length", (double)variadicArgs.Length, 2);
46  
-            x.Put("callee", f, 2);
  48
+        /// <summary>
  49
+        /// Gets or sets the link map.
  50
+        /// </summary>
  51
+        /// <value>
  52
+        /// The link map.
  53
+        /// </value>
  54
+        public ArgLink[] LinkMap { get; set; }
47 55
 
48  
-            if (!object.ReferenceEquals(variadicArgs, null))
49  
-            {
50  
-                var i = f.MetaData.ParameterStorage.Length;
51  
-                for (; i < variadicArgs.Length; i++)
52  
-                {
53  
-                    x.Put((uint)i, variadicArgs[i]);
54  
-                }
55  
-            }
  56
+        /// <summary>
  57
+        /// Gets or sets whether the <see cref="ArgumentsObject"/> should be limited
  58
+        /// to the private scope or not.
  59
+        /// </summary>
  60
+        /// <value>
  61
+        /// 	<c>true</c> if the <see cref="ArgumentsObject"/> should be limited
  62
+        /// to the private scope; otherwise <c>false</c>.
  63
+        /// </value>
  64
+        public BoxedValue[] PrivateScope { get; set; }
56 65
 
57  
-            return x;
58  
-        }
  66
+        /// <summary>
  67
+        /// Gets or sets the shared scope.
  68
+        /// </summary>
  69
+        /// <value>
  70
+        /// The shared scope.
  71
+        /// </value>
  72
+        public BoxedValue[] SharedScope { get; set; }
59 73
 
  74
+
  75
+        /// <summary>
  76
+        /// Creates a <see cref="ArgumentsObject"/> for the specified <see cref="FunctionObject"/>
  77
+        /// <paramref name="f"/>.
  78
+        /// </summary>
  79
+        /// <param name="f">The function for which to create an <see cref="ArgumentsObject"/>.</param>
  80
+        /// <param name="privateScope">The private scope.</param>
  81
+        /// <param name="sharedScope">The shared scope.</param>
  82
+        /// <param name="namedArgsPassed">The number of named arguments that is passed.</param>
  83
+        /// <param name="extraArgs">The extra arguments.</param>
  84
+        /// <returns>
  85
+        /// A <see cref="ArgumentsObject"/> for the specified <see cref="FunctionObject"/>
  86
+        /// <paramref name="f"/>.
  87
+        /// </returns>
60 88
         public static ArgumentsObject CreateForFunction(
61 89
             FunctionObject f,
62 90
             BoxedValue[] privateScope,
63 91
             BoxedValue[] sharedScope,
64 92
             int namedArgsPassed,
65  
-            BoxedValue[] extraArgs
66  
-        )
  93
+            BoxedValue[] extraArgs)
67 94
         {
  95
+            // TODO: This method has no tests. [asbjornu]
  96
+
68 97
             var length = namedArgsPassed + extraArgs.Length;
69 98
             var storage =
70 99
                 f.MetaData.ParameterStorage
@@ -77,39 +106,138 @@ BoxedValue[] extraArgs
77 106
                     storage,
78 107
                     privateScope,
79 108
                     sharedScope
80  
-                );
  109
+                    );
81 110
 
82 111
             x.CopyLinkedValues();
83 112
             x.Put("constructor", f.Env.Constructors.Object);
84  
-            x.Put("length", (double)length, DescriptorAttrs.DontEnum);
  113
+            x.Put("length", length, DescriptorAttrs.DontEnum);
85 114
             x.Put("callee", f, DescriptorAttrs.DontEnum);
86 115
 
87 116
             for (var i = 0; i < extraArgs.Length; ++i)
88  
-            {
89 117
                 x.Put((uint)(i + namedArgsPassed), extraArgs[i]);
  118
+
  119
+            return x;
  120
+        }
  121
+
  122
+
  123
+        /// <summary>
  124
+        /// Creates a <see cref="ArgumentsObject"/> for the specified variadic
  125
+        /// <see cref="FunctionObject"/> <paramref name="f"/>.
  126
+        /// </summary>
  127
+        /// <param name="f">The f.</param>
  128
+        /// <param name="privateScope">The private scope.</param>
  129
+        /// <param name="sharedScope">The shared scope.</param>
  130
+        /// <param name="variadicArgs">The variadic args.</param>
  131
+        /// <returns>
  132
+        /// A <see cref="ArgumentsObject"/> for the specified variadic <see cref="FunctionObject"/>
  133
+        /// <paramref name="f"/>.
  134
+        /// </returns>
  135
+        public static ArgumentsObject CreateForVariadicFunction(
  136
+            FunctionObject f,
  137
+            BoxedValue[] privateScope,
  138
+            BoxedValue[] sharedScope,
  139
+            BoxedValue[] variadicArgs)
  140
+        {
  141
+            // TODO: This method has no tests. [asbjornu]
  142
+
  143
+            var x =
  144
+                new ArgumentsObject(
  145
+                    f.Env,
  146
+                    f.MetaData.ParameterStorage,
  147
+                    privateScope,
  148
+                    sharedScope
  149
+                    );
  150
+
  151
+            x.CopyLinkedValues();
  152
+            x.Put("constructor", f.Env.Constructors.Object, 0xffffff08);
  153
+            x.Put("length", variadicArgs.Length, 2);
  154
+            x.Put("callee", f, 2);
  155
+
  156
+            // TODO: R# says this expression will always evaluate to false. Rewrite or remove? [asbjornu]
  157
+            if (!ReferenceEquals(variadicArgs, null))
  158
+            {
  159
+                var i = f.MetaData.ParameterStorage.Length;
  160
+                for (; i < variadicArgs.Length; i++)
  161
+                    x.Put((uint)i, variadicArgs[i]);
90 162
             }
91 163
 
92 164
             return x;
93 165
         }
94 166
 
95  
-        public void CopyLinkedValues()
  167
+
  168
+        /// <summary>
  169
+        /// Deletes the property at the specified <paramref name="index"/>.
  170
+        /// </summary>
  171
+        /// <param name="index">The index of the property to delete.</param>
  172
+        /// <returns>
  173
+        ///   <c>true</c> if the deletion succeeded; otherwise <c>false</c>.
  174
+        /// </returns>
  175
+        public override bool Delete(uint index)
96 176
         {
97  
-            for (var i = 0; i < LinkMap.Length; ++i)
  177
+            var ii = (int)index;
  178
+
  179
+            if (LinkIntact && ii < LinkMap.Length)
98 180
             {
99  
-                var link = LinkMap[i];
  181
+                CopyLinkedValues();
  182
+                LinkIntact = false;
  183
+                PrivateScope = null;
  184
+                SharedScope = null;
  185
+            }
  186
+
  187
+            return base.Delete(index);
  188
+        }
  189
+
  190
+
  191
+        /// <summary>
  192
+        /// Gets the property at the specified <paramref name="index"/>.
  193
+        /// </summary>
  194
+        /// <param name="index">The index of the property to get.</param>
  195
+        /// <returns>
  196
+        /// The property at the specified <paramref name="index"/>.
  197
+        /// </returns>
  198
+        public override BoxedValue Get(uint index)
  199
+        {
  200
+            var ii = (int)index;
  201
+
  202
+            if (LinkIntact && ii < LinkMap.Length)
  203
+            {
  204
+                var link = LinkMap[ii];
100 205
                 switch (link.Item1)
101 206
                 {
102 207
                     case ParameterStorageType.Private:
103  
-                        base.Put((uint)i, PrivateScope[link.Item2]);
104  
-                        break;
  208
+                        return PrivateScope[link.Item2];
105 209
 
106 210
                     case ParameterStorageType.Shared:
107  
-                        base.Put((uint)i, SharedScope[link.Item2]);
108  
-                        break;
  211
+                        return SharedScope[link.Item2];
109 212
                 }
110 213
             }
  214
+
  215
+            return base.Get(index);
  216
+        }
  217
+
  218
+
  219
+        /// <summary>
  220
+        /// Determines whether the <see cref="ArgumentsObject"/> has a
  221
+        /// property at the specified <paramref name="index"/>.
  222
+        /// </summary>
  223
+        /// <param name="index">The index.</param>
  224
+        /// <returns>
  225
+        ///   <c>true</c> if the <see cref="ArgumentsObject"/> has a
  226
+        /// property at the specified <paramref name="index"/>; otherwise, <c>false</c>.
  227
+        /// </returns>
  228
+        public override bool Has(uint index)
  229
+        {
  230
+            return
  231
+                (LinkIntact && (int)index < LinkMap.Length)
  232
+                || base.Has(index);
111 233
         }
112 234
 
  235
+
  236
+        /// <summary>
  237
+        /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>.
  238
+        /// </summary>
  239
+        /// <param name="index">The index.</param>
  240
+        /// <param name="value">The value.</param>
113 241
         public override void Put(uint index, BoxedValue value)
114 242
         {
115 243
             var ii = (int)index;
@@ -132,56 +260,51 @@ public override void Put(uint index, BoxedValue value)
132 260
             base.Put(index, value);
133 261
         }
134 262
 
  263
+
  264
+        /// <summary>
  265
+        /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>.
  266
+        /// </summary>
  267
+        /// <param name="index">The index.</param>
  268
+        /// <param name="value">The value.</param>
135 269
         public override void Put(uint index, double value)
136 270
         {
137 271
             Put(index, BoxedValue.Box(value));
138 272
         }
139 273
 
  274
+
  275
+        /// <summary>
  276
+        /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>
  277
+        /// with the provided <paramref name="tag"/>.
  278
+        /// </summary>
  279
+        /// <param name="index">The index.</param>
  280
+        /// <param name="value">The value.</param>
  281
+        /// <param name="tag">The tag.</param>
140 282
         public override void Put(uint index, object value, uint tag)
141 283
         {
142 284
             Put(index, BoxedValue.Box(value, tag));
143 285
         }
144 286
 
145  
-        public override BoxedValue Get(uint index)
146  
-        {
147  
-            var ii = (int)index;
148 287
 
149  
-            if (LinkIntact && ii < LinkMap.Length)
  288
+        /// <summary>
  289
+        /// Copies the linked values.
  290
+        /// </summary>
  291
+        public void CopyLinkedValues()
  292
+        {
  293
+            // TODO: Can this method be made private? [asbjornu]
  294
+            for (var i = 0; i < LinkMap.Length; ++i)
150 295
             {
151  
-                var link = LinkMap[ii];
  296
+                var link = LinkMap[i];
152 297
                 switch (link.Item1)
153 298
                 {
154 299
                     case ParameterStorageType.Private:
155  
-                        return PrivateScope[link.Item2];
  300
+                        base.Put((uint)i, PrivateScope[link.Item2]);
  301
+                        break;
156 302
 
157 303
                     case ParameterStorageType.Shared:
158  
-                        return SharedScope[link.Item2];
  304
+                        base.Put((uint)i, SharedScope[link.Item2]);
  305
+                        break;
159 306
                 }
160 307
             }
161  
-
162  
-            return base.Get(index);
163  
-        }
164  
-
165  
-        public override bool Has(uint index)
166  
-        {
167  
-            return
168  
-                (LinkIntact && (int)index < LinkMap.Length)
169  
-                || base.Has(index);
170  
-        }
171  
-
172  
-        public override bool Delete(uint index)
173  
-        {
174  
-            var ii = (int)index;
175  
-
176  
-            if (LinkIntact && ii < LinkMap.Length)
177  
-            {
178  
-                CopyLinkedValues();
179  
-                LinkIntact = false;
180  
-                PrivateScope = null;
181  
-                SharedScope = null;
182  
-            }
183  
-
184  
-            return base.Delete(index);
185 308
         }
186 309
     }
187  
-}
  310
+}
4  Src/IronJS/IronJS.fsproj
@@ -20,7 +20,7 @@
20 20
     <OutputPath>bin\Debug\</OutputPath>
21 21
     <DefineConstants>TRACE;DEBUG</DefineConstants>
22 22
     <WarningLevel>4</WarningLevel>
23  
-    <DocumentationFile>bin\Debug\IronJS.XML</DocumentationFile>
  23
+    <DocumentationFile>bin\Debug\IronJS.xml</DocumentationFile>
24 24
     <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
25 25
     <WarningsAsErrors />
26 26
     <PlatformTarget>AnyCPU</PlatformTarget>
@@ -33,7 +33,7 @@
33 33
     <DefineConstants>
34 34
     </DefineConstants>
35 35
     <WarningLevel>3</WarningLevel>
36  
-    <DocumentationFile>bin\Release\IronJS.XML</DocumentationFile>
  36
+    <DocumentationFile>bin\Release\IronJS.xml</DocumentationFile>
37 37
     <PlatformTarget>AnyCPU</PlatformTarget>
38 38
     <EnableUnmanagedDebugging>true</EnableUnmanagedDebugging>
39 39
   </PropertyGroup>

1 note on commit 4ac68b9

Asbjørn Ulsberg
Collaborator

I'm trying to add documentation to the IronJS.Runtime and hope that this commit is small enough baby steps. Does it look okay? Should I continue adding documentation and cleaning up the C# code?

Asbjørn Ulsberg

ReSharper removed this cast to double, I assume that's ok?

Asbjørn Ulsberg

I've made all public fields into properties, since that's the recommended design of the .NET framework.

John Gietzen

As long as it calls the same overload as before, it should be fine.

Wesley Wiser

I'm curious, why didn't you use the auto-property syntax for this property?

Asbjørn Ulsberg

Good question. I could of course just have set the auto-property's value to true in the constructor instead of the backing field on initialization. I guess it's a matter of design; should fields be initialized on declaration or in the constructor? If the latter, this could just as well have been an auto-property (which is actually my preference).

Asbjørn Ulsberg

Yea, according to R#, that's the case. I haven't done any tests for the fact, though.

Please sign in to comment.
Something went wrong with that request. Please try again.