Permalink
Browse files

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

…ect.cs specificallly.
  • Loading branch information...
1 parent cf52365 commit 4ac68b942809f5d09b7782e0d5d71335bc6d257d @asbjornu asbjornu committed Sep 9, 2011
Showing with 203 additions and 78 deletions.
  1. +2 −0 Src/IronJS.Runtime/IronJS.Runtime.csproj
  2. +199 −76 Src/IronJS.Runtime/Objects/ArgumentsObject.cs
  3. +2 −2 Src/IronJS/IronJS.fsproj
@@ -21,6 +21,7 @@
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
+ <DocumentationFile>bin\Debug\IronJS.Runtime.xml</DocumentationFile>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
@@ -29,6 +30,7 @@
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
+ <DocumentationFile>bin\Release\IronJS.Runtime.xml</DocumentationFile>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|x86'">
<DebugSymbols>true</DebugSymbols>
@@ -1,19 +1,25 @@
using System;
-using System.Collections.Generic;
using System.Linq;
-using System.Text;
namespace IronJS.Runtime
{
using ArgLink = Tuple<ParameterStorageType, int>;
+ /// <summary>
+ /// A <see cref="CommonObject"/> used as an argument to a <see cref="FunctionObject"/>.
+ /// </summary>
public class ArgumentsObject : CommonObject
{
- public BoxedValue[] PrivateScope;
- public BoxedValue[] SharedScope;
- public ArgLink[] LinkMap;
- public bool LinkIntact = true;
@asbjornu
asbjornu Sep 9, 2011 collaborator

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

+ private bool linkIntact = true;
+
+ /// <summary>
+ /// Initializes a new instance of the <see cref="ArgumentsObject"/> class.
+ /// </summary>
+ /// <param name="env">The environment.</param>
+ /// <param name="linkMap">The link map.</param>
+ /// <param name="privateScope">The private scope.</param>
+ /// <param name="sharedScope">The shared scope.</param>
public ArgumentsObject(
Environment env,
ArgLink[] linkMap,
@@ -26,45 +32,68 @@ public class ArgumentsObject : CommonObject
LinkMap = linkMap;
}
- public static ArgumentsObject CreateForVariadicFunction(
- FunctionObject f,
- BoxedValue[] privateScope,
- BoxedValue[] sharedScope,
- BoxedValue[] variadicArgs)
+
+ /// <summary>
+ /// Gets or sets a value indicating whether to keep the link intact.
+ /// </summary>
+ /// <value>
+ /// <c>true</c> to keep the link intact; otherwise, <c>false</c>.
+ /// </value>
+ public bool LinkIntact
@wesleywiser
wesleywiser Sep 9, 2011

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

@asbjornu
asbjornu Sep 10, 2011 collaborator

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).

{
- var x =
- new ArgumentsObject(
- f.Env,
- f.MetaData.ParameterStorage,
- privateScope,
- sharedScope
- );
+ get { return this.linkIntact; }
+ set { this.linkIntact = value; }
+ }
- x.CopyLinkedValues();
- x.Put("constructor", f.Env.Constructors.Object, (uint)0xffffff08);
- x.Put("length", (double)variadicArgs.Length, 2);
- x.Put("callee", f, 2);
+ /// <summary>
+ /// Gets or sets the link map.
+ /// </summary>
+ /// <value>
+ /// The link map.
+ /// </value>
+ public ArgLink[] LinkMap { get; set; }
- if (!object.ReferenceEquals(variadicArgs, null))
- {
- var i = f.MetaData.ParameterStorage.Length;
- for (; i < variadicArgs.Length; i++)
- {
- x.Put((uint)i, variadicArgs[i]);
- }
- }
+ /// <summary>
+ /// Gets or sets whether the <see cref="ArgumentsObject"/> should be limited
+ /// to the private scope or not.
+ /// </summary>
+ /// <value>
+ /// <c>true</c> if the <see cref="ArgumentsObject"/> should be limited
+ /// to the private scope; otherwise <c>false</c>.
+ /// </value>
+ public BoxedValue[] PrivateScope { get; set; }
- return x;
- }
+ /// <summary>
+ /// Gets or sets the shared scope.
+ /// </summary>
+ /// <value>
+ /// The shared scope.
+ /// </value>
+ public BoxedValue[] SharedScope { get; set; }
+
+ /// <summary>
+ /// Creates a <see cref="ArgumentsObject"/> for the specified <see cref="FunctionObject"/>
+ /// <paramref name="f"/>.
+ /// </summary>
+ /// <param name="f">The function for which to create an <see cref="ArgumentsObject"/>.</param>
+ /// <param name="privateScope">The private scope.</param>
+ /// <param name="sharedScope">The shared scope.</param>
+ /// <param name="namedArgsPassed">The number of named arguments that is passed.</param>
+ /// <param name="extraArgs">The extra arguments.</param>
+ /// <returns>
+ /// A <see cref="ArgumentsObject"/> for the specified <see cref="FunctionObject"/>
+ /// <paramref name="f"/>.
+ /// </returns>
public static ArgumentsObject CreateForFunction(
FunctionObject f,
BoxedValue[] privateScope,
BoxedValue[] sharedScope,
int namedArgsPassed,
- BoxedValue[] extraArgs
- )
+ BoxedValue[] extraArgs)
{
+ // TODO: This method has no tests. [asbjornu]
+
var length = namedArgsPassed + extraArgs.Length;
var storage =
f.MetaData.ParameterStorage
@@ -77,39 +106,138 @@ BoxedValue[] extraArgs
storage,
privateScope,
sharedScope
- );
+ );
x.CopyLinkedValues();
x.Put("constructor", f.Env.Constructors.Object);
- x.Put("length", (double)length, DescriptorAttrs.DontEnum);
@asbjornu
asbjornu Sep 9, 2011 collaborator

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

@otac0n
otac0n Sep 9, 2011 collaborator

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

@asbjornu
asbjornu Sep 10, 2011 collaborator

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

+ x.Put("length", length, DescriptorAttrs.DontEnum);
x.Put("callee", f, DescriptorAttrs.DontEnum);
for (var i = 0; i < extraArgs.Length; ++i)
- {
x.Put((uint)(i + namedArgsPassed), extraArgs[i]);
+
+ return x;
+ }
+
+
+ /// <summary>
+ /// Creates a <see cref="ArgumentsObject"/> for the specified variadic
+ /// <see cref="FunctionObject"/> <paramref name="f"/>.
+ /// </summary>
+ /// <param name="f">The f.</param>
+ /// <param name="privateScope">The private scope.</param>
+ /// <param name="sharedScope">The shared scope.</param>
+ /// <param name="variadicArgs">The variadic args.</param>
+ /// <returns>
+ /// A <see cref="ArgumentsObject"/> for the specified variadic <see cref="FunctionObject"/>
+ /// <paramref name="f"/>.
+ /// </returns>
+ public static ArgumentsObject CreateForVariadicFunction(
+ FunctionObject f,
+ BoxedValue[] privateScope,
+ BoxedValue[] sharedScope,
+ BoxedValue[] variadicArgs)
+ {
+ // TODO: This method has no tests. [asbjornu]
+
+ var x =
+ new ArgumentsObject(
+ f.Env,
+ f.MetaData.ParameterStorage,
+ privateScope,
+ sharedScope
+ );
+
+ x.CopyLinkedValues();
+ x.Put("constructor", f.Env.Constructors.Object, 0xffffff08);
+ x.Put("length", variadicArgs.Length, 2);
+ x.Put("callee", f, 2);
+
+ // TODO: R# says this expression will always evaluate to false. Rewrite or remove? [asbjornu]
+ if (!ReferenceEquals(variadicArgs, null))
+ {
+ var i = f.MetaData.ParameterStorage.Length;
+ for (; i < variadicArgs.Length; i++)
+ x.Put((uint)i, variadicArgs[i]);
}
return x;
}
- public void CopyLinkedValues()
+
+ /// <summary>
+ /// Deletes the property at the specified <paramref name="index"/>.
+ /// </summary>
+ /// <param name="index">The index of the property to delete.</param>
+ /// <returns>
+ /// <c>true</c> if the deletion succeeded; otherwise <c>false</c>.
+ /// </returns>
+ public override bool Delete(uint index)
{
- for (var i = 0; i < LinkMap.Length; ++i)
+ var ii = (int)index;
+
+ if (LinkIntact && ii < LinkMap.Length)
{
- var link = LinkMap[i];
+ CopyLinkedValues();
+ LinkIntact = false;
+ PrivateScope = null;
+ SharedScope = null;
+ }
+
+ return base.Delete(index);
+ }
+
+
+ /// <summary>
+ /// Gets the property at the specified <paramref name="index"/>.
+ /// </summary>
+ /// <param name="index">The index of the property to get.</param>
+ /// <returns>
+ /// The property at the specified <paramref name="index"/>.
+ /// </returns>
+ public override BoxedValue Get(uint index)
+ {
+ var ii = (int)index;
+
+ if (LinkIntact && ii < LinkMap.Length)
+ {
+ var link = LinkMap[ii];
switch (link.Item1)
{
case ParameterStorageType.Private:
- base.Put((uint)i, PrivateScope[link.Item2]);
- break;
+ return PrivateScope[link.Item2];
case ParameterStorageType.Shared:
- base.Put((uint)i, SharedScope[link.Item2]);
- break;
+ return SharedScope[link.Item2];
}
}
+
+ return base.Get(index);
+ }
+
+
+ /// <summary>
+ /// Determines whether the <see cref="ArgumentsObject"/> has a
+ /// property at the specified <paramref name="index"/>.
+ /// </summary>
+ /// <param name="index">The index.</param>
+ /// <returns>
+ /// <c>true</c> if the <see cref="ArgumentsObject"/> has a
+ /// property at the specified <paramref name="index"/>; otherwise, <c>false</c>.
+ /// </returns>
+ public override bool Has(uint index)
+ {
+ return
+ (LinkIntact && (int)index < LinkMap.Length)
+ || base.Has(index);
}
+
+ /// <summary>
+ /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>.
+ /// </summary>
+ /// <param name="index">The index.</param>
+ /// <param name="value">The value.</param>
public override void Put(uint index, BoxedValue value)
{
var ii = (int)index;
@@ -132,56 +260,51 @@ public override void Put(uint index, BoxedValue value)
base.Put(index, value);
}
+
+ /// <summary>
+ /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>.
+ /// </summary>
+ /// <param name="index">The index.</param>
+ /// <param name="value">The value.</param>
public override void Put(uint index, double value)
{
Put(index, BoxedValue.Box(value));
}
+
+ /// <summary>
+ /// Puts the <paramref name="value"/> at the specified <paramref name="index"/>
+ /// with the provided <paramref name="tag"/>.
+ /// </summary>
+ /// <param name="index">The index.</param>
+ /// <param name="value">The value.</param>
+ /// <param name="tag">The tag.</param>
public override void Put(uint index, object value, uint tag)
{
Put(index, BoxedValue.Box(value, tag));
}
- public override BoxedValue Get(uint index)
- {
- var ii = (int)index;
- if (LinkIntact && ii < LinkMap.Length)
+ /// <summary>
+ /// Copies the linked values.
+ /// </summary>
+ public void CopyLinkedValues()
+ {
+ // TODO: Can this method be made private? [asbjornu]
+ for (var i = 0; i < LinkMap.Length; ++i)
{
- var link = LinkMap[ii];
+ var link = LinkMap[i];
switch (link.Item1)
{
case ParameterStorageType.Private:
- return PrivateScope[link.Item2];
+ base.Put((uint)i, PrivateScope[link.Item2]);
+ break;
case ParameterStorageType.Shared:
- return SharedScope[link.Item2];
+ base.Put((uint)i, SharedScope[link.Item2]);
+ break;
}
}
-
- return base.Get(index);
- }
-
- public override bool Has(uint index)
- {
- return
- (LinkIntact && (int)index < LinkMap.Length)
- || base.Has(index);
- }
-
- public override bool Delete(uint index)
- {
- var ii = (int)index;
-
- if (LinkIntact && ii < LinkMap.Length)
- {
- CopyLinkedValues();
- LinkIntact = false;
- PrivateScope = null;
- SharedScope = null;
- }
-
- return base.Delete(index);
}
}
-}
+}
@@ -20,7 +20,7 @@
<OutputPath>bin\Debug\</OutputPath>
<DefineConstants>TRACE;DEBUG</DefineConstants>
<WarningLevel>4</WarningLevel>
- <DocumentationFile>bin\Debug\IronJS.XML</DocumentationFile>
+ <DocumentationFile>bin\Debug\IronJS.xml</DocumentationFile>
<TreatWarningsAsErrors>false</TreatWarningsAsErrors>
<WarningsAsErrors />
<PlatformTarget>AnyCPU</PlatformTarget>
@@ -33,7 +33,7 @@
<DefineConstants>
</DefineConstants>
<WarningLevel>3</WarningLevel>
- <DocumentationFile>bin\Release\IronJS.XML</DocumentationFile>
+ <DocumentationFile>bin\Release\IronJS.xml</DocumentationFile>
<PlatformTarget>AnyCPU</PlatformTarget>
<EnableUnmanagedDebugging>true</EnableUnmanagedDebugging>
</PropertyGroup>

1 comment on commit 4ac68b9

@asbjornu
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?

Please sign in to comment.