Just wondering whether there is any support for comments considered as documentation for enums and classes members (methods and fields / properties) in PowerShell?
If you're referring to the equivalent of Comment-Based Help, I've seen no indication of any. However, if you're writing classes or enums, you are also presumably writing scripts or script cmdlets/advanced functions that rely on them; it wouldn't be unreasonable to document the classes or enums in the scripts/etc. that use them.
Trevor Sullivan provides a link below to building your own about_Topic help data files; this represents another possibility, and one that may well be more appropriate, depending on how you're using your classes/enums.
Related
Is there anyway we can read scala doc comments using reflection. My requirement is to read the #group tag value and use it for counting how many functions are there for each group
No, you can't use Scala reflection to access documentation comments. The reason is simple: comments are, almost by definition, not part of the program. Therefore, it is logically impossible for them to be available via reflection.
In Python, for example, documentation is available from the running program (in fact, even without using reflection), because the documentation is not hidden away in comments, but rather simply assigned to a field of the object that is being documented. Many Lisps (e.g. Clojure), and also Ioke and Seph work that way, too.
In Newspeak, what they call "comments" is available using reflection, but that's because what they call "comments" are not really comments, it is more like arbitrary metadata that can be attached to objects. It is in fact more similar to an annotation in Scala than a comment.
In Scala, documentation is written in comments, and comments are not part of the program (they are literally equivalent to whitespace in the Scala Language Specification), and therefore, cannot possibly be part of the program and thus cannot possibly be accessed via reflection.
I'm having a hard time deciphering Scala API documentation.
For example, I've defined a timestamp for use in a database.
def postedDate = column[Timestamp]("posted_date", O NotNull, O Default new Timestamp(Calendar.getInstance.getTimeInMillis), O DBType("timestamp"))
If I hadn't read several examples, of which none were in the API doc, how could I construct this statement? From the Column documentation how could I know the parameters?
I guessed it had something to do with TimestampTypeMapperDelegate but it is still not crystal clear how to use it.
The first thing to note from the scaladoc for Column is that it is abstract, so you probably want to deal directly with one if its subclasses. For example, NamedColumn.
Other things to note are that it has a type parameter and the constructor takes an implicit argument of a TypeMapper of the same parameter type. The docs for TypeMapper provide an example of how to create a custom one, but if you look at the subclasses, there are plenty of provided ones (such as timestamp). The fact that the argument is declared as implicit suggests that there could be one in scope, and if so, it will automatically be used as the parameter without explicitly stating that. If there isn't an implicit in scope that satisfies the requirement, you'll have to provide it.
The next think to note is that a TypeMapper is a trait that extends a function with an argument of a BasicProfile and a TypeMapperDelegate result. Basically what's going on here is the definition of a type mapper is separated from the implementation. This is done to support multiple flavors of database. If look at the subclasses of BasicProfile, it will become apparent that ScalaQuery supports quite a few, and as we know, their implementations are sometimes quite different.
If you chase the docs for a while, you end up at the BasicTypeMapperDelegates trait that has a bunch of vals in it with delegates for each of the basic types (including timestamps).
BasicTable defines a method called column (which you've found), and the intent of the column method is to shield you from having to know anything about TypeMappers and Delegates as long as you are using standard types.
So, I guess to answer your question about whether there is enough information in the API docs, I'd personally say yes, but the docs could be enhanced with better descriptions of classes, objects, traits and methods.
All that said, I've always found that leveraging examples, API docs, and even the source code of the project provides a robust way of getting up to speed on most open source projects. To be quite blunt, many of these projects (including ScalaQuery) have saved me countless hours of work, but probably cost the author(s) countless hours of personal time to create and make available. These are not necessarily commercial products, and we as consumers shouldn't hold them to the same standards that we hold for-fee products. If you find docs inadequate, contribute!
I need to define simple classes and interfaces (Ex. IClassInterface) in a language neutral way and then use a variety of code generation tools to generate the code files in a variety of languages such as C#, Java, etc... Does anyone know of a standard; ratified or otherwise; that I can use for the neutral representation. I know UML is often used for creating diagrams, but I am actually looking for something that can easily be parsed, extended, and used to drive other automated processes. Maybe this is actually possible with UML, although I am not sure what the markup language might look like if one exists.
I could create my own definition using XML or something similar, but I would prefer to avoid reinventing the wheel if possible.
UML
I think you might be looking for XMI (XML Metadata Interchange)
There is IDL (for example, Google's protocol buffers), and WSDL, which can be used to produce interfaces and classes by many web service frameworks. (You typically do not have to use the generated code as an actual webservice.)
The wikipedia entry for IDL lists a number of implementations of IDL. Although IDL is mainly for describing interfaces, some implementations also use it to describe objects (e.g. Microsoft IDL.)
We seems to be abstracting a lot of logic way from web pages and creating "helper" classes. Sadly, these classes are all sounding the same, e.g
ADHelper, (Active Directory)
AuthenicationHelper,
SharePointHelper
Do other people have a large number of classes with this naming convention?
I would say that it qualifies as a code smell, but remember that a code smell doesn't necessarily spell trouble. It is something you should look into and then decide if it is okay.
Having said that I personally find that a name like that adds very little value and because it is so generic the type may easily become a bucket of non-related utility methods. I.e. a helper class may turn into a Large Class, which is one of the common code smells.
If possible I suggest finding a type name that more closely describes what the methods do. Of course this may prompt additional helper classes, but as long as their names are helpful I don't mind the numbers.
Some time ago I came across a class called XmlHelper during a code review. It had a number of methods that obviously all had to do with Xml. However, it wasn't clear from the type name what the methods had in common (aside from being Xml-related). It turned out that some of the methods were formatting Xml and others were parsing Xml. So IMO the class should have been split in two or more parts with more specific names.
As always, it depends on the context.
When you work with your own API I would definitely consider it a code smell, because FooHelper indicates that it operates on Foo, but the behavior would most likely belong directly on the Foo class.
However, when you work with existing APIs (such as types in the BCL), you can't change the implementation, so extension methods become one of the ways to address shortcomings in the original API. You could choose to names such classes FooHelper just as well as FooExtension. It's equally smelly (or not).
Depends on the actual content of the classes.
If a huge amount of actual business logic/business rules are in the helper classes, then I would say yes.
If the classes are really just helpers that can be used in other enterprise applications (re-use in the absolute sense of the word -- not copy then customize), then I would say the helpers aren't a code smell.
It is an interesting point, if a word becomes 'boilerplate' in names then its probably a bit whiffy - if not quite a real smell. Perhaps using a 'Helper' folder and then allowing it to appear in the namespace keeps its use without overusing the word?
Application.Helper.SharePoint
Application.Helper.Authentication
and so on
In many cases, I use classes ending with Helper for static classes containing extension methods. Doesn't seem smelly to me. You can't put them into a non-static class, and the class itself does not matter, so Helper is fine, I think. Users of such a class won't see the class name anyway.
The .NET Framework does this as well (for example in the LogicalTreeHelper class from WPF, which just has a few static (non-extension) methods).
Ask yourself if the code would be better if the code in your helper class would be refactored to "real" classes, i.e. objects that fit into your class hierarchy. Code has to be somewhere, and if you can't make out a class/object where it really belongs to, like simple helper functions (hence "Helper"), you should be fine.
I wouldn't say that it is a code smell. In ASP.NET MVC it is quite common.
Background
this post explains how one can consume extension methods in Powershell
http://community.bartdesmet.net/blogs/bart/archive/2007/09/06/extension-methods-in-windows-powershell.aspx
Compare this to what someone does in C# - they add a "using SomeAssembly" and all the extension methods are loaded.
My questions
Did this get simpler Powershell 2.0. And if so, what does one do to use extension methods in Powershell 2.0? I have checked the publically available documentation and installed the CTP and am not seeing anything that is helping.
It doesn't get easier in V2, but there is an extension mechanism which you might not be aware of.
I believe that part of the problem is in PowerShell's handling (or lack thereof) of generics.
Also, for extension methods to be applied, the typed collections would have to be enforced, which is difficult in PowerShell. PowerShell, as a dynamic language, supports building collections of various types and most collections are represented as arrays of Object. Extension methods require the parameters to be inferred from the collection type and then the predicate checked to be of the correct type.
If your concern is for some LINQ like functions, there are a number of cmdlets that provide the same functionality in working with object collections.
PowerShell's extended type system allows you to add methods to various types by adding an xml file or modifying an existing one (creating a new one is the recommended path). Jeffrey Snover demonstrates doing this with adding a ScriptProperty to the Object class in this blog post.
It's not quite the same, but it could get the job done.