I'm trying to author documentation for some C++/CX interfaces as XML comments. The result will be parsed by Doxygen as well as by VC++'s own /doc option.
In the documentation for each interface member, I can use <see cref="..."/> syntax to crossreference members of the same interface, as well as to other types that have been forward declared. But what is the proper syntax for referencing a member of a different interface?
All of my attempts produce compiler warnings:
C4638: XML document comment applied to ...: reference to unknown symbol ...
I've seen this question and its answers, but you can't forward declare members of interface classes, can you? And due to circularity, I cannot always make sure to include the declaration of each referenced interface before the one containing the reference.
If the interface were classes, my understanding is that the XML comments could be put on the implementations of the functions rather than their declarations, but for an interface there isn't any implementations of the members that I could move the XML comments to.
Related
Racket and Xtext are both considered as language workbenches, but they are based on different concepts and workflows.
As an experienced Xtext user, I find it difficult to adapt my thought process to Racket.
In Xtext, the grammar of a language is converted into, or mapped to, a set of classes (also called a metamodel).
Xtext also generates a parser that converts a source file into a set of instances of those classes. A scoping API allows to resolve named references, so that the result is an object graph (also called a model) rather than an abstract syntax tree (AST).
Such a model can be queried, transformed, or fed into a template engine to generate code.
In Racket, the reader produces an AST in the form of a syntax object. However, most examples that I have found seem to make an ad-hoc use of this syntax object. Either they are toy languages that do not need a complete object graph, or they are too complex and it is difficult to infer a general methodology.
For my current language project, after struggling with syntax objects, I have created the equivalent of a metamodel using Racket structs. Then it was fairly easy to convert a syntax object into an object graph that I could manipulate as if it were a model in EMF. However, I feel like I am not using syntax objects the way they are intended to be.
Here are my questions:
What tools or APIs are available to work on syntax objects and achieve a similar ease-of-use as a model-driven framework?
Are there documents that describe a general language development methodology in Racket, that could be applied to non-trivial languages?
Are there documents that explain the Racket way, compared to Xtext or any other model-driven language framework?
EDIT:
Based on the documentation for Metaprogramming helpers, syntax classes can be used to specify and compose syntax patterns, and attach attributes to their elements. They can achieve a similar purpose as the classes of a metamodel.
However, as far as I can see, syntax classes are not classes, and syntax objects are not linked to syntax classes in a class-instance relationship.
This has the following consequences:
Syntax classes do not support inheritance directly, but we can achieve a similar effect with ~or* and attribute declarations for subclasses.
Syntax classes do not come with accessors for their attributes: you have to call syntax-parse every time you want to read an attribute.
At this point, there are still two missing features that are not addressed in the documentation that I have found:
Traversing a syntax tree from child to parent: how can I get a reference to the syntax object enclosing a given syntax object?
Scoping: how can I define specific scoping rules for my language?
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.
I'm trying to learn/understand Rx, specifically RxJS, and keep seeing references to IObservable, IObserver, etc.
Can anyone tell me what the leading I means and/or where it comes from?
From my searching, it looks like the <T> is for the type. If this is wrong or naive, I'd appreciate some clarification on this as well.
Thanks!
In ye olden days of MFC for C++, Microsoft had Hungarian notation down to a very irritating artform, where all concrete classes were prefixed with C and their COM interfaces with I, this does help avoid the conflict where a COM interface and class might share the same name and so muddy your project.
Part of this notation carried over into .NET, except only interfaces kept the I prefix, but classes and other types dropped their Cs. This does make non-interface-heavy code easier to look at, but can cause ambiguity if you begin a class name with a 2-letter acronym beginning with I (as two-letter acronyms must be completely capitalised according to the the .NET style guidelines), but this is rare.
(I note that generic type name placeholders are prefixed with T too, e.g. TKey and TValue in Dictionary).
An example of why this is necessary is when dealing with collections in .NET, if you're building a reusable library and don't want to expose implementation details (e.g. if you use List<T> or T[] as an underlying collection field type), you can use IList<T> or IReadOnlyList<T> which are interfaces. If the interface was simply called List<T> it would conflict with the actual type List<T>, and ReadOnlyList<T> (an interface) might get confused with ReadOnlyCollection<T> (a class).
You might argue that this wouldn't be a problem if classes and interfaces had a different namespace. C does this: struct types and scalars exist in different namespaces, which unfortunately means that every time a struct type name is used, its usage must be prefixed with struct (e.g. a declaration: struct Foo foo). People workaround this by using typedef with anonymous structs, but I feel the end-result is messy (and the Linux kernel coding guidelines prohibit this too).
In Java, however, interfaces are not prefixed with I but instead have class-like names. Whether this is "correct" or "better" is entirely up for debate. C++ does not have interface types, just pure-abstract classes and multiple-inheritance, so the I prefix isn't typically seen at all outside of COM.
There are some constructs that don't have equivalents in java. Examples would be
named parameters
instance private members
Where/How does Scala store the information necessary for this stuff (some kind of flag in the first case, the parameter names in the second case?
If I get it right this has to get stored in the byte code, since it works even if I just have a compiled library without the source code!?
This information is captured in an annotation named ScalaSig in the class file (see this answer for an example).
You can view the (not very human-friendly) annotation with javap -verbose, or parse it using an internal API, but in general neither should be necessary.
I see the word thrown around often, and I may have used it myself in code and libraries over time, but I never really got it. In most write-ups I came across, they just went on expecting you to figure it out.
What is a Class Factory? Can someone explain the concept?
Here's some supplemental information that may help better understand several of the other shorter, although technically correct, answers.
In the strictest sense a Class Factory is a function or method that creates or selects a class and returns it, based on some condition determined from input parameters or global context. This is required when the type of object needed can't be determined until runtime. Implementation can be done directly when classes are themselves objects in the language being used, such as Python.
Since the primary use of any class is to create instances of itself, in languages such as C++ where classes are not objects that can be passed around and manipulated, a similar result can often be achieved by simulating "virtual constructors", where you call a base-class constructor but get back an instance of some derived class. This must be simulated because constructors can't really be virtual✶ in C++, which is why such object—not class—factories are usually implemented as standalone functions or static methods.
Although using object-factories is a simple and straight-forward scheme, they require the manual maintenance of a list of all supported types in the base class' make_object() function, which can be error-prone and labor-intensive (if not over-looked). It also violates encapsulation✶✶ since a member of base class must know about all of the base's concrete descendant classes (now and in the future).
✶ Virtual functions are normally resolved "late" by the actual type of object referenced, but in the case of constructors, the object doesn't exist yet, so the type must be determined by some other means.
✶✶ Encapsulation is a property of the design of a set of classes and functions where the knowledge of the implementation details of a particular class or function are hidden within it—and is one of the hallmarks of object-oriented programming.
Therefore the best/ideal implementations are those that can handle new candidate classes automatically when they're added, rather than having only a certain finite set currently hardcoded into the factory (although the trade-off is often deemed acceptable since the factory is the only place requiring modification).
James Coplien's 1991 book Advanced C++: Programming Styles and Idioms has details on one way to implement such virtual generic constructors in C++. There are even better ways to do this using C++ templates, but that's not covered in the book which predates their addition to the standard language definition. In fact, C++ templates are themselves class factories since they instantiate a new class whenever they're invoked with different actual type arguments.
Update: I located a 1998 paper Coplien wrote for EuroPLoP titled C++ Idioms where, among other things, he revises and regroups the idioms in his book into design-pattern form à la the 1994 Design Patterns: Elements of Re-Usable Object-Oriented Software book. Note especially the Virtual Constructor section (which uses his Envelope/Letter pattern structure).
Also see the related answers here to the question Class factory in Python as well as the 2001 Dr. Dobb's article about implementing them with C++ Templates titled Abstract Factory, Template Style.
A class factory constructs instances of other classes. Typically, the classes they create share a common base class or interface, but derived classes are returned.
For example, you could have a class factory that took a database connection string and returned a class implementing IDbConnection such as SqlConnection (class and interface from .Net)
A class factory is a method which (according to some parameters for example) returns you a customised class (not instantiated!).
The Wikipedia article gives a pretty good definition: http://en.wikipedia.org/wiki/Factory_pattern
But probably the most authoritative definition would be found in the Design Patterns book by Gamma et al. (commonly called the Gang of Four Book).
I felt that this explains it pretty well (for me, anyway). Class factories are used in the factory design pattern, I think.
Like other creational patterns, it [the factory design pattern]
deals with the problem of creating
objects (products) without specifying
the exact class of object that will be
created. The factory method design
pattern handles this problem by
defining a separate method for
creating the objects, which subclasses
can then override to specify the
derived type of product that will be
created. More generally, the term
factory method is often used to refer
to any method whose main purpose is
creation of objects.
http://en.wikipedia.org/wiki/Factory_method_pattern
Apologies if you've already read this and found it to be insufficient.