I'm currently using a multi-package open source framework that exposes dozens of classes/objects as type aliases in a root package, apparently solely for the purpose of making wildcard importing easy.
unfortunately, because these type aliases have the same name as the actual qualified type, they always come up first in the search function, which wastes time and valuable screen space.
is there an annotation I can put in front of a type alias to stop it from showing up in search? I don't want to omit it entirely from the documentation, because it obviously isn't irrelevant, it's just that nobody would look for these aliases by name. also note that I'm generating these docs for my own personal perusal, so we don't need to debate whether hiding members from search is bad practice for a public framework.
Related
I was trying to understand the different sections in the package declaration file (.dec) of an EDK2 module, however I can't seem to figure out why some GUID definitions are under the [GUIDs] section and some are under the [Protocols] section or [Ppis] section. Is there a reason why they should not be under the same section, especially from the perspective of the EDK2 build process?
So, this is half an answer at most, but:
A GUID, ultimately, is nothing other than a 128-bit value statistically guaranteed to be unique (if generated using the defined method).
The [Guids] section of the .dec defines GUIDs that point to generic data structures, variable namespaces, things...
The [Protocols] section defines discoverable UEFI APIs, whereas [Ppis] defines PEI (Pre-EFI) APIs.
Ultimately, this becomes relevant when processing module .inf files, which declare which [Guids], [Protocols] and [Ppis] they require to build. I.e., you could possibly get away with just declaring everything as GUIDs - but then you'd loose any sanity checking preventing you from using PPIs in DXE, or the other way around.
By convention, REST methods should be nouns and should answer the question "What?" rather than "How?".
So, given that I only need to make find-by-id method, I can easily come up with the RESTful path /foo/{id}, where the part in brackets is substituted by some number.
Now, I also need to add find-by-name method, but I cannot use /foo/{name} as it's already taken.
I cannot also add 'name'-section to the path (i.e. the path would look like /foo/name/{name}), because it would mean "This method returns Foo's name".
What can be an appropriate way to compose this path?
There's nothing wrong with having both /foo/{name} and /foo/{id}. URI semantics are transparent to REST. Trying to embed behavior in URI doesn't make much sense in REST, where that behavior is supposed to come from the media type, the URI merely gives its location. /foo/name/{name} doesn't mean "this method returns Foo's name". It means whatever the source of the hyperlink giving you that URI template says it does.
The appropriate way to do what you want is having /foo returning an hyperlink title "Find Foo by name" or something like that. This hyperlink can be an URI template that when expanded with the name will retrieve a search result with the desired Foo, if it exists.
That uritemplate can be /foo/{name}, /foo?name={name}, /search?type=foo&name={name}, or even something totally unrelated like /my/api/is/a/mess?name={name}. It doesn't really matter, because all the client will do is retrieve that uritemplate, expand it, and retrieve the resource.
Obviously, you're encouraged to think carefully about your paths and make them meaningful and intuitive to client developers, but adopting one or other style doesn't make your API more or less RESTful and you can't say it's more or less appropriate. If you're thinking too much about that, it's probably because you're API is not hypertext driven, and not RESTful at all. Other implementation details, like your framework, will probably have more of a voice on the degree of appropriateness of one or the other than the REST constraints. For instance, some frameworks may have trouble with routing to both foo/{name} and /foo/{id}, but as I said above, that's not a problem at all for REST.
I guess the right way to it is smt like
/foo?name=bar
By querying in this way you will be able return several foo with same name. If for one name there are always no more than one foo perhaps name should be your id.
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!
What's the Pascal way to do C's #include "code.h", Python's import code, etc.?
Pascal uses
uses
to import other modules.
While you can explicitly {$INCLUDE a file it's rarely done other than for configuration files containing compiler switches. The only time I've ever done it was long ago when I wanted two versions of the code identical except one used coprocessor-only datatypes and the other didn't. (And how many people these days even know that single and double types used to require either an expensive additional chip or a slow emulator?)
If you include the same code in two places you will get two copies of it in your .EXE. If you include the same type definition in two places you'll get two types with the same name and since Pascal uses strict typing they will not match.
The normal mechanic is as Greg Hewgill says, to use the file you want. Anything that appears in the interface of the file you use is visible, anything that's only in the implementation is not visible. This is an all-or-nothing process, you don't specify what you are bringing in. Think of the C# using command.
Unlike the C# version it's absolutely mandatory. You can't use fully qualified names to get around it.
Often when I create new classes, I first create a new interface. I name the methods of my interface exactly as I would like them to behave. A colleague of mine prefers to have these method names being more abstract, ie: areConditionsMet(). The reason, he wants to hide the 'implementation details'.
IMO implementation details are different from the expected behavior. Could anyone perhaps give more insight. My goal is to reach a common ground with my colleague.
Your method names should describe what the method does, but not how it does it. The example you gave is a pretty poor method name, but it's better than isXGreatherThan1AndLessThan6(). Without knowing the details about what it should do, I would say that it should be specific to the problem at hand, but general enough that the implementation could change without affecting the name itself, i.e., you don't want the name of the method to be brittle. An example might be isTemperatureWithinRange() - that describes what I'm checking but doesn't describe how it's accomplished. The user of the method should be confident that the output will reflect whether the temperature is within a certain range -- whether this is supplied as an argument or defined by the contract of the class, is immaterial.
Interfaces should represent some behavior or capability and not the way it is to be accomplished. Users of interfaces should not be interested in the way a target is achieved, they just want to know its done.
Implementation issues should not be included within the name of methods for that exact reason. The name of the table updated as a result of this method or the technology used has nothing to do in your domain object's method's name.
However from your question it is hard to say what is the exact case at hand.
If you could provide more details perhaps i could provide an additional help.
The names of your interface methods should leave the user of the interface in no doubt about what the method proposes to do from a functional perspective. If the implementation matches that, well and good.
Based on your updated comments:
Sounds to me like you need two methods: isModified() and hasProperties(). Leave it up to the user (or higher layer) of the domain object to determine if a particular criteria is fulfilled.
An interface should also be designed with the view that after it is released it will never be changed. By saying isDomainObjectModifiedAndHasProperties() you are setting in concrete that this is the criteria of fullfilment (regardless of any future unforseen implementation).