Re: Docs status (was Re: [Fwd: [projects-dev] Milestone 3 status update])

Svata Dedic wrote:

> Ondrej Rypacek wrote:
>
>>>
>>>
>>>> If there was some OpenAPI-backed
>>>>     Object getSomething(Object tag);
>>>> with a clearly defined contract between `tag' and the returned 
>>>> value's type, I would prefer to use that call. We have not any, so 
>>>> we invented ContentDescriptor.
>>>>
>> Is that a joke?! You didn't mean it, did you ?
>> :-( Sadly enough, that's how the apis are made
>>
> I am curious about a pattern that would allow to request a service 
> from an object (node, DataObject, FileObject) that someone passes to 
> your code from outside that would not look as a joke.
> One thing is to have factory methods on the service class something like
>     Service get(Node|FileObject|DataObject place)
> but that has another problem - when a new place-type appears, you have 
> to update the service interface, which seems as a similar joke to me.
>
> -Svata

The problem is, that the method -its name and signature-

    Object getSomething(Object )

contains no information at all. It is too generic to specify anything. 
You could, in the same manner define the class

class TooGeneric {
    Object getSomething(Object );
    void setSomething(Object );
    void doSomething(Object );
}

and derive all your classes from it. But TooGeneric contains NO 
INFORMATION. The API with it or without it is the same (isomorphic ).

Back to your example. Having a "Service" in your apis that can do 
ANYTHING (specified by Object), which is associated to ANY object by 
ANYTHING (Object) , is telling you NOTHING and you should probably 
remove it and think of some better way of *specifying* the thing you 
want to do. If it really is anything, then you should ask for more 
specific requirements .

- Ondra