Add ContentSuggestionsMediator

ios/chrome/browser/ui/content_suggestions/content_suggestions_data_source.h

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef IOS_CHROME_BROWSER_UI_CONTENT_SUGGESTIONS_CONTENT_SUGGESTIONS_DATA_SOURCE_H_
+#define IOS_CHROME_BROWSER_UI_CONTENT_SUGGESTIONS_CONTENT_SUGGESTIONS_DATA_SOURCE_H_
+
+@protocol ContentSuggestionsData;
+@protocol ContentSuggestionsDataSink;
+
+// DataSource for the content suggestions. Provides the suggestions data in a
+// format compatible with objective-c.

[lpromero, 2017/01/26 10:10:20]

Nit: Objective-C

[gambard, 2017/01/30 15:19:17]

Done.

+@protocol ContentSuggestionsDataSource
+
+// The data sink that will be notified when the data change.
+@property(nonatomic, weak) id<ContentSuggestionsDataSink> dataSink;

[lpromero, 2017/01/26 10:10:20]

It's basically a dataSource delegate?

[marq (ping after 24h), 2017/01/27 12:44:55]

The 'dataSink' naming is something I proposed a while back. This seems like a
good place to see how it feels.

(in general, I like defining specialized cases of the delegate pattern and
giving them their own conventions; the data source/delegate distinction in table
and collection views seems like a good precedent for this).

+
+// Returns all the data currently available.

[marq (ping after 24h), 2017/01/27 12:44:55]

What is returned if no data is available? (I would suggest an empty array).

[gambard, 2017/01/30 15:19:17]

Done.

+- (NSArray<id<ContentSuggestionsData>>*)getData;

[lpromero, 2017/01/26 10:10:20]

s/getData/currentData

[marq (ping after 24h), 2017/01/27 12:44:55]

Except the important noun is 'suggestions', not 'data'. I would prefer
-allSuggestions here.

('get' in method names is reserved the indirect return of values via in-out
parameters, such as [NSBezierPath getLineDash:count:phase:])

[gambard, 2017/01/30 15:19:17]

Done.

+
+// Returns the new data.

[lpromero, 2017/01/26 10:10:20]

When dataSink receives the dataAvailable message, does getData/currentData
already contains the new data? I think it should.

Do you need the diff?

If yes, then keep this but s/getMoreData/availableData.
If no, remove this second method and just requery getData/currentData.

[marq (ping after 24h), 2017/01/27 12:44:55]

Definitey consider this approach.

Also I would prefer if the method name was more specific about what suggestion
it was fetching; 'moreData' feels a bit like NSSet's 'anyObject', where you have
no assurances about what will be returned. So maybe one of:

- recentSuggestions
- updatedSuggestions
- latestSuggestions

(please avoid 'newSuggestions', since that has implications for memory
semantics).

[gambard, 2017/01/30 15:19:17]

I will remove this method for now as I am not sure of how the data sink asks for
more data.
The question being: who keeps a cache with the downloaded data. If it is the
data source this methods does not make sense.

+- (NSArray<id<ContentSuggestionsData>>*)getMoreData;

[marq (ping after 24h), 2017/01/27 12:44:55]

Document what is returned when there is no further data; I would suggest an
empty array rather than nil.

[gambard, 2017/01/30 15:19:17]

Done.

+
+@end
+
+#endif  // IOS_CHROME_BROWSER_UI_CONTENT_SUGGESTIONS_CONTENT_SUGGESTIONS_DATA_SOURCE_H_