Grammar and Clarity in Code Comments
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
The node whose children will be placed in a UL I dont know what a UL is but assuming it's a collection I would use 'inserted' instead of 'placed'
I decided against "whose" because a node is not a person. I also considered "which's", but that seems awkward and seems to personify the node by implying it can possess something (maybe that's not a bad thing though). Regarding "placed" vs "inserted", that's a matter of perspective. A UL is the HTML element used to represent a bulleted list (the children being LI elements). The HtmlGenericControl class, which is used to create a UL from .Net code, is not a collection class, but it does contain a property (Controls) that is a collection. So it's conceptually a collection, but does not act exactly like one. Still, the "contract" for this method does not say how the children will end up in the UL. The collection in the HtmlGenericControl could be initialized with dummy values, and then those dummy values could be overwritten with each child. So I don't think it is important to differentiate between "inserted" and "placed".
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
The node whose children will be placed in a UL I dont know what a UL is but assuming it's a collection I would use 'inserted' instead of 'placed'
_Josh_ wrote:
The node whose children will be placed in a UL
That's what I would say.
_Josh_ wrote:
I dont know what a UL is
A foster home I'd guess. :-D
Luc Pattyn [My Articles] Nil Volentibus Arduum
-
I decided against "whose" because a node is not a person. I also considered "which's", but that seems awkward and seems to personify the node by implying it can possess something (maybe that's not a bad thing though). Regarding "placed" vs "inserted", that's a matter of perspective. A UL is the HTML element used to represent a bulleted list (the children being LI elements). The HtmlGenericControl class, which is used to create a UL from .Net code, is not a collection class, but it does contain a property (Controls) that is a collection. So it's conceptually a collection, but does not act exactly like one. Still, the "contract" for this method does not say how the children will end up in the UL. The collection in the HtmlGenericControl could be initialized with dummy values, and then those dummy values could be overwritten with each child. So I don't think it is important to differentiate between "inserted" and "placed".
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
AspDotNetDev wrote:
I decided against "whose" because a node is not a person.
It doesn't have to be. "Which car?" "The one whose tire is flat"
AspDotNetDev wrote:
Regarding "placed" vs "inserted", that's a matter of perspective.
More a matter of taste. In the c++ stl all collections have an insert method so that is why I prefer that term. The entire thing smells a bit to me. The only reference to 'UL' is in the comments and bears no obvious relationship to 'ChildList' which is what the method name suggests it creates or the HtmlGenericControl type it returns. Perhaps it's obvious to someone with some web programming knowledge but it's not to me. If you're creating something derived from HtmlGenericControlthen return the more specific type as you know what it is.
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
I'm not worrying over the grammar yet, the semantics seem to be confusing.
AspDotNetDev wrote:
Creates the UL to hold the children of the specified node.
AspDotNetDev wrote:
The UL that holds the children
That is confusing in two ways: 1. to hold and holds seem contradicting each other. 2. the specified node: there's two of them, parent and current. Which one is it? Maybe: Creates the UL and populates it with the children of the parent node. And currentNode is a mystery to me. PS: I don't see the need to put it all in one sentence, sometimes two is better. e.g.: parentNode: a specific node; it's children will... :doh:
Luc Pattyn [My Articles] Nil Volentibus Arduum
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
Taking a step back, I am looking at the whole comment block and the name of the function, and it is not entirely clear how everything relates. My guess is the 'specified' node from the summary is the parent node? The question is, how does the node for the current page relate to the parent node? As far as the comment for the parentNode, I would do something like:
'''<param name="parentNode">The node to be awarded custody of the children.</param>
-
I decided against "whose" because a node is not a person. I also considered "which's", but that seems awkward and seems to personify the node by implying it can possess something (maybe that's not a bad thing though). Regarding "placed" vs "inserted", that's a matter of perspective. A UL is the HTML element used to represent a bulleted list (the children being LI elements). The HtmlGenericControl class, which is used to create a UL from .Net code, is not a collection class, but it does contain a property (Controls) that is a collection. So it's conceptually a collection, but does not act exactly like one. Still, the "contract" for this method does not say how the children will end up in the UL. The collection in the HtmlGenericControl could be initialized with dummy values, and then those dummy values could be overwritten with each child. So I don't think it is important to differentiate between "inserted" and "placed".
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
AspDotNetDev wrote:
I decided against "whose" because a node is not a person.
Still sounds better, and also seems to be right: http://www.merriam-webster.com/dictionary/whose[^]
-
AspDotNetDev wrote:
I decided against "whose" because a node is not a person.
It doesn't have to be. "Which car?" "The one whose tire is flat"
AspDotNetDev wrote:
Regarding "placed" vs "inserted", that's a matter of perspective.
More a matter of taste. In the c++ stl all collections have an insert method so that is why I prefer that term. The entire thing smells a bit to me. The only reference to 'UL' is in the comments and bears no obvious relationship to 'ChildList' which is what the method name suggests it creates or the HtmlGenericControl type it returns. Perhaps it's obvious to someone with some web programming knowledge but it's not to me. If you're creating something derived from HtmlGenericControlthen return the more specific type as you know what it is.
I think you are right about "whose". According to this, "whose" can be used as the possessive form of "which". Since I was trying to do "which's", it makes sense to use "whose" instead.
_Josh_ wrote:
The entire thing smells a bit to me. The only reference to 'UL' is in the comments and bears no obvious relationship to 'ChildList' which is what the method name suggests it creates or the HtmlGenericControl type it returns. Perhaps it's obvious to someone with some web programming knowledge but it's not to me. If you're creating something derived from HtmlGenericControlthen return the more specific type as you know what it is.
Only some HTML controls have a specific representation in .Net. One of them that does not, UL, requires use of the general purpose HtmlGenericControl. I would use the term "HTML list" (or something similar) in the code comments rather than "UL", but I felt it more appropriate to indicate the more concrete version of what is actually happening to make it easier to understand.
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
I think you are right about "whose". According to this, "whose" can be used as the possessive form of "which". Since I was trying to do "which's", it makes sense to use "whose" instead.
_Josh_ wrote:
The entire thing smells a bit to me. The only reference to 'UL' is in the comments and bears no obvious relationship to 'ChildList' which is what the method name suggests it creates or the HtmlGenericControl type it returns. Perhaps it's obvious to someone with some web programming knowledge but it's not to me. If you're creating something derived from HtmlGenericControlthen return the more specific type as you know what it is.
Only some HTML controls have a specific representation in .Net. One of them that does not, UL, requires use of the general purpose HtmlGenericControl. I would use the term "HTML list" (or something similar) in the code comments rather than "UL", but I felt it more appropriate to indicate the more concrete version of what is actually happening to make it easier to understand.
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
AspDotNetDev wrote:
Only some HTML controls have a specific representation in .Net. One of them that does not, UL, requires use of the general purpose HtmlGenericControl. I would use the term "HTML list" (or something similar) in the code comments rather than "UL", but I felt it more appropriate to indicate the more concrete version of what is actually happening to make it easier to understand.
You could call the method CreateULGenericControl() perhaps Also, who do you specify one possible return value in the remarks section? Wouldn't you specify the return value as "The UL holding the children or NULL if there are no children"?
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
Wellllllll,,, Firstly I see confusion with the descriptions - parentNode and currentNode parentNode is the node containing the children to be added to the UL currentNode is what? The node into which the UL is to be inserted? Or is it actually the page? It probably doesn't matter, but I don't see that the current node is necessary, and parentNode confuses me a bit, as I think of it as being the parent to the UL, not the data for the UL. As for the comment - I'd probably go with something like The node containing the items to be placed in the UL and the returns comment I would then change to The UL containing the items from the parentNode
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
AspDotNetDev wrote:
Only some HTML controls have a specific representation in .Net. One of them that does not, UL, requires use of the general purpose HtmlGenericControl. I would use the term "HTML list" (or something similar) in the code comments rather than "UL", but I felt it more appropriate to indicate the more concrete version of what is actually happening to make it easier to understand.
You could call the method CreateULGenericControl() perhaps Also, who do you specify one possible return value in the remarks section? Wouldn't you specify the return value as "The UL holding the children or NULL if there are no children"?
_Josh_ wrote:
You could call the method CreateULGenericControl() perhaps
Nah, there are many functions in the class that can return UL's. I named it more towards what it's creating the UL for (it's part of a class that is essentially converting a very specific in-memory hierarchy to HTML).
_Josh_ wrote:
Also, who do you specify one possible return value in the remarks section?
I always assume that null may be returned from a function that has a return type that is nullable. Though if it is intended to direct functionality (i.e., the null is expected in some cases), I will either put it in the return comment or the remarks comment. I just happened to side on putting it in the remarks comment this time (I see remarks as not only a place to put things that don't fit anywhere else, but also a place to put additional information that would make the other sections excessively long). Basically, I like to keep the most important information where it will most likely be used.
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
parentNode - The node that contains the children to be placed in a UL.
Steve _________________ I C(++) therefore I am
-
I'm not worrying over the grammar yet, the semantics seem to be confusing.
AspDotNetDev wrote:
Creates the UL to hold the children of the specified node.
AspDotNetDev wrote:
The UL that holds the children
That is confusing in two ways: 1. to hold and holds seem contradicting each other. 2. the specified node: there's two of them, parent and current. Which one is it? Maybe: Creates the UL and populates it with the children of the parent node. And currentNode is a mystery to me. PS: I don't see the need to put it all in one sentence, sometimes two is better. e.g.: parentNode: a specific node; it's children will... :doh:
Luc Pattyn [My Articles] Nil Volentibus Arduum
Luc Pattyn wrote:
Maybe: Creates the UL and populates it with the children of the parent node
Good idea. This might be more appropriate for my specific use: "Creates a UL that contains the children of the specified node."
Luc Pattyn wrote:
And currentNode is a mystery to me
It would make more sense if you were familiar with the class this function is part of and the types of nodes that are being passed around (that was one of the things I obscured in my OP).
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
Wellllllll,,, Firstly I see confusion with the descriptions - parentNode and currentNode parentNode is the node containing the children to be added to the UL currentNode is what? The node into which the UL is to be inserted? Or is it actually the page? It probably doesn't matter, but I don't see that the current node is necessary, and parentNode confuses me a bit, as I think of it as being the parent to the UL, not the data for the UL. As for the comment - I'd probably go with something like The node containing the items to be placed in the UL and the returns comment I would then change to The UL containing the items from the parentNode
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
We have a website that is hosted in a CMS. Each page is represented in-memory as a "node". It is a hierarchical data structure. The currentNode is the node that represents the page currently being viewed by the user. It may be used by this class to, for example, change the classes on various HTML elements, such as UL's and LI's. The parentNode is the node that the function happens to be working with.
_Maxxx_ wrote:
The node containing the items to be placed in the UL
I like that. :thumbsup:
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
AspDotNetDev wrote:
The node for which its children will be placed in a UL.
More proper, but still clunky:
The node in which its children will be placed in a UL.
Slightly more clear:
The node that holds children nodes which will be placed in a UL.
Slightly more obscure:
The node for unsorted children.
Slightly more irritated:
Why don't you read the #*(%!$& documentation.
m.bergman
-- For Bruce Schneier, quanta only have one state : afraid.
-
AspDotNetDev wrote:
I decided against "whose" because a node is not a person.
It doesn't have to be. "Which car?" "The one whose tire is flat"
AspDotNetDev wrote:
Regarding "placed" vs "inserted", that's a matter of perspective.
More a matter of taste. In the c++ stl all collections have an insert method so that is why I prefer that term. The entire thing smells a bit to me. The only reference to 'UL' is in the comments and bears no obvious relationship to 'ChildList' which is what the method name suggests it creates or the HtmlGenericControl type it returns. Perhaps it's obvious to someone with some web programming knowledge but it's not to me. If you're creating something derived from HtmlGenericControlthen return the more specific type as you know what it is.
"The one with the flat tire". The one who's tire is flat sounds wrong to me.
-
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
I'd go for a starter which defines the type of entity and then a description. This means you can do ...
''' <param name="parentNode">(Node) This node contains the child nodes that are to be copied to the UL.</param>
''' <param name="currentNode">(Node) The node that corresponds to the current page.</param>
''' <returns>(Node) The UL node that holds the children after they have been copied.</returns> -
Suppose I created this function (changed a bit to protect the innocent):
''' <summary>
''' Creates the UL to hold the children of the specified node.
''' </summary>
''' <param name="parentNode">The node for which its children will be placed in a UL.</param>
''' <param name="currentNode">The node of the current page.</param>
''' <returns>The UL that holds the children.</returns>
''' <remarks>
''' If there are no children, null will be returned.
''' All descendants will be handled.
''' </remarks>
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
' Yada, yada, yada...
End FunctionThe comment I wrote for
parentNodeseems a little off for some reason. It might be because it's overly formal or verbose, but I'm thinking the grammar is wrong in some way. I could just write "The children of this node will be placed in a UL." However, I want to place "the node" at the beginning (I think this is a certain type of sentence, but I'm not good enough with grammar to know what to call it... something relating to the subject/object ordering). How would you change that comment ("The node for which its children will be placed in a UL")? Or would you leave it as is?Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
We have a website that is hosted in a CMS. Each page is represented in-memory as a "node". It is a hierarchical data structure. The currentNode is the node that represents the page currently being viewed by the user. It may be used by this class to, for example, change the classes on various HTML elements, such as UL's and LI's. The parentNode is the node that the function happens to be working with.
_Maxxx_ wrote:
The node containing the items to be placed in the UL
I like that. :thumbsup:
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
AspDotNetDev wrote:
The currentNode is the node that represents the page currently being viewed by the user. ... The parentNode is the node that the function happens to be working with.
Maybe it makes more sense in context of the whole API, but to me with just this snippet, the names seem to be almost exactly opposite the definitions. Is that why it's so confusing to write the documentation? Perhaps it's not a problem with the comments so much as the method signature. A couple questions, looking at just the parameters: - Why have "Node" in the name at all? We know it's type based on the function signature. It smacks of post-fix Hungarian notation. - Neither of these are HTML nodes, correct? If I understand properly, they're nodes in the domain structure. If so, then perhaps replace "Node" with "Source" (as in the source of the data). The returned result would be the destination. - Rather than "current" and "parent", perhaps "page" and "current" (where what's now parent becomes current). Backing up a bit to look at the whole signature:
Private Shared Function CreateChildrenList(ByVal parentNode As Node, ByVal currentNode As Node) As HtmlGenericControl
There are three actors: children in the function name, parent in the first parameter and current in the second parameter. And, if I understand correctly, the children that are being returned are the items from parent converted to some HTML representation. The parent parameter is a container in the domain object hierarchy and the current is another container in the domain hierarchy. This seems pretty confusing. Parent and children aren't the same types, nor do the children belong to the parent. Current is more of a global context, not the current thing this function is interested in. Assuming I understand all this correctly, I'd suggest something more along these lines:
Private Shared Function ConvertItems(ByVal itemContainer As Node, ByVal page As Node) As HtmlGenericControl
"Convert" emphasizes the type differences between what goes in and what comes out. By having "Items" in both the function name and first parameter, it shows these as related. By renaming the last parameter, it emphasizes its global nature. Depending on how the items are referenced in the Node type, I might even name the first parameter just "items" instead of "itemContainer". I know it's not what you asked, but hopefully it helps anyway. :)