Roland responded to my e-mailed review and has graciously allowed me to post his response here. In a follow-up he also notes that user-defined rules, including regular expressions, WILL be part of a future version:
> [...Method names that to not start with a verb...]
Yes, GhostDoc needs some improvement in that area, but it's kind of hard to do right. But it would be ok if at least some of those method names would be handled correctly.
Rules matching a prefix (e.g. "To" as in "ToString") are relatively easy and will come in a version after 1.10 (which is pretty close to a code freeze)
For a method like DataBind a dictionary based approach could be chosen (exakt match -> generate pre-defined text). This would also be nice for very common methods like Equals. It's already on my TODO list, but it has lower priority than other items.
> Where it really falls short is when I use prefixes to separate > and organize methods - for example I have a common web service > that exposes web methods from multiple business rule classes - > in this case I use the original class name as the prefix > followed by an underscore - e.g. Company_SearchParent. > For this GD returns "Company_s the search parent."
Ok something like this could be handled by a list of prefixes that should be ignored -- I already do something similar for explicit interface implementations, so it should be pretty simple. Thanks for the suggestions, I'll definitely put that on my list
> What I'd like to see is some way to set filters for (regular) > expressions that GD should match, as well as filters that > it should NOT match.
That's something I have thought about (although I'm not a regex user); the problem is how the user would configure such a rule. Sure, entering a regex in a text field is simple, but it could be pretty tedious to open and close the dialog over and over again until the expression is right.
As the number of rules grows in the future, some sort of a "rule preview" (I won't say debugger) feature becomes necessary to try out which rule actually matched e.g. the method signature. Obviously a regexp rule would benefit from that.
> Actually, come to think of it, I believe GD needs to have some > special setting for underscores to handle the default names of > event handlers
Oh yes ;-) This gets on my nerves, too ... It's definitely on my list (it didn't make 1.10, though)!
> Additionally, there needs to be user changeable settings for > common terms: the term ID is one I'd like to keep as ID; i. d. > looks strange to me.
Ok... ID is a very special case (which is handled incorrectly by my word-detection algorithm). Do you have additional examples?
Acronyms are user-definable in 1.10, but ID is actually different as it remains unchanged during text generation.
> Similarly, an event handler's EventArgs parameter, which VS.NET > by default names e, ought to be trapped and expanded on > (of course here you run into potential conflicts with Exceptions, > which some people also give the name e - but that is why I use > exc for Exceptions.).
Actually, that's not a problem because I process both type and name (even though most rules do not make use of this). EventArgs and On... methods are already on my list.
As I mentioned earlier, Version 1.10 is frozen and on its way to a release (which is a long road of testing and writing documentation) so be sure to check the GhostDoc website or my blog from time to time.
Version 1.20 will be the first to implement feature requests by users.
If you have any suggestions, keep them coming...
Again, thanks for your feedback,
Roland _____________________________________________________
Monday, August 16, 2004 3:49:00 PM
Roland Weigelt has an excellent little add-in to VS.NET, called GhostDoc. It recently won 1st price in Roy's add in contest, and it was well deserved. I downloaded it last week and tried it out on our current project, and I can see that it has great potential but falls short in a few areas. I mentioned that on Roland's blog, and he asked me for further feedback which I provided by email - but thought I'd also share here:
Mostly the method names that GhostDoc has trouble resolving are “bad” names that I had chosen. This is to be expected - it's a simple parser, not HAL - and in some cases GD actually helped point these instances out to me. But it also has problems with common composite-action styled method names like DataBind – “Datas the bind. “ wasn’t exactly what I was looking for (“Databind” works fine of course).
Where it really falls short is when I use prefixes to separate and organize methods – for example I have a common web service that exposes web methods from multiple business rule classes – in this case I use the original class name as the prefix followed by an underscore – e.g. Company_SearchParent. For this GD returns “Company_s the search parent.”
What I’d like to see is some way to set filters for (regular) expressions that GD should match, as well as filters that it should NOT match. Along with the excellent filters you have already included, that should make it capable of handling most anything (in English at least). That way I could say – exclude prefixes that end in _ so in the above example GD would just see SearchParent, which it handles quite nicely: “Searches the parent.”
Actually, come to think of it, I believe GD needs to have some special setting for underscores to handle the default names of event handlers: for example, my listDetail control has an InitializeLayout event; so VS.Net generates the method name listDetail_InitializeLayout. The expected summary of this method would be “Initializes the layout of the listDetail.” But GD generates “Lists the detail_ initialize layout.”. If GD was set to by default treat anything preceding an underscore as the indirect object of an action, that would solve both this situation and that above – I would get “Searches the parent of the Company” which is exactly what I’m doing. But some kind of regex filters would still be great…
Additionally, there needs to be user changeable settings for common terms: the term ID is one I’d like to keep as ID; i. d. looks strange to me. Similarly, an event handler’s EventArgs parameter, which VS.NET by default names e, ought to be trapped and expanded on (of course here you run into potential conflicts with Exceptions, which some people also give the name e – but that is why I use exc for Exceptions…).
Overall, this is a great tool, but I think these changes would make it even better.
posted by Oskar Austegard at 11:32 AM on Aug 16, 2004
"Brief GhostDoc v. 1.0.2 review"
1 Comment -
Roland responded to my e-mailed review and has graciously allowed me to post his response here. In a follow-up he also notes that user-defined rules, including regular expressions, WILL be part of a future version:
_____________________________________________________
Hi Oskar,
thanks for your extensive feedback!
> [...Method names that to not start with a verb...]
Yes, GhostDoc needs some improvement in that area, but it's
kind of hard to do right. But it would be ok if at least some
of those method names would be handled correctly.
Rules matching a prefix (e.g. "To" as in "ToString") are relatively
easy and will come in a version after 1.10 (which is pretty close
to a code freeze)
For a method like DataBind a dictionary based approach could
be chosen (exakt match -> generate pre-defined text). This would
also be nice for very common methods like Equals.
It's already on my TODO list, but it has lower priority than
other items.
> Where it really falls short is when I use prefixes to separate
> and organize methods - for example I have a common web service
> that exposes web methods from multiple business rule classes -
> in this case I use the original class name as the prefix
> followed by an underscore - e.g. Company_SearchParent.
> For this GD returns "Company_s the search parent."
Ok something like this could be handled by a list of prefixes
that should be ignored -- I already do something similar for
explicit interface implementations, so it should be pretty
simple. Thanks for the suggestions, I'll definitely put that
on my list
> What I'd like to see is some way to set filters for (regular)
> expressions that GD should match, as well as filters that
> it should NOT match.
That's something I have thought about (although I'm not a
regex user); the problem is how the user would configure
such a rule. Sure, entering a regex in a text field is simple,
but it could be pretty tedious to open and close the dialog
over and over again until the expression is right.
As the number of rules grows in the future, some sort of a
"rule preview" (I won't say debugger) feature becomes necessary
to try out which rule actually matched e.g. the method signature.
Obviously a regexp rule would benefit from that.
> Actually, come to think of it, I believe GD needs to have some
> special setting for underscores to handle the default names of
> event handlers
Oh yes ;-) This gets on my nerves, too ... It's definitely
on my list (it didn't make 1.10, though)!
> Additionally, there needs to be user changeable settings for
> common terms: the term ID is one I'd like to keep as ID; i. d.
> looks strange to me.
Ok... ID is a very special case (which is handled incorrectly
by my word-detection algorithm). Do you have additional examples?
Acronyms are user-definable in 1.10, but ID is actually different
as it remains unchanged during text generation.
> Similarly, an event handler's EventArgs parameter, which VS.NET
> by default names e, ought to be trapped and expanded on
> (of course here you run into potential conflicts with Exceptions,
> which some people also give the name e - but that is why I use
> exc for Exceptions.).
Actually, that's not a problem because I process both type and
name (even though most rules do not make use of this).
EventArgs and On... methods are already on my list.
As I mentioned earlier, Version 1.10 is frozen and on its way to
a release (which is a long road of testing and writing documentation)
so be sure to check the GhostDoc website or my blog from time to time.
Version 1.20 will be the first to implement feature requests
by users.
If you have any suggestions, keep them coming...
Again, thanks for your feedback,
Roland
_____________________________________________________
Monday, August 16, 2004 3:49:00 PM