Mailing-List: contact dev-help@flink.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@flink.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAGr9p8DmCc8YC6u0LV-ag3xuF2zhts-J=ycquEOAUDTS5fXSCQ@mail.gmail.com>
References: 
 <CAGr9p8BJkJsHTxp_PTUfhb657V6p8_H910Wi=uSjP+UcdHtMYA@mail.gmail.com>
 <CAGco--YQT0kyD-Gy3S+fgZmYiwahOMC5AqZeA+yhgCh+wqH2tQ@mail.gmail.com>
 <CANZa=Gtt=hdCt43cO=3WUhxLK2qEBE9SUp_KvaUcgp3eCsripA@mail.gmail.com>
 <CAGr9p8DmCc8YC6u0LV-ag3xuF2zhts-J=ycquEOAUDTS5fXSCQ@mail.gmail.com>
From: Ufuk Celebi <uce@apache.org>
Date: Thu, 19 Nov 2015 18:38:14 +0100
Message-ID: 
 <CAKiyyaEK8SjrRzL340E9mvE-dwUxkthvAHOwsxopBrRDUcaHng@mail.gmail.com>
Subject: Re: [DISCUSS] Include import statements in documentation code
 examples
To: dev@flink.apache.org
Content-Type: multipart/alternative; boundary=001a11c3cc8e9bf8710524e83b85

--001a11c3cc8e9bf8710524e83b85
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

I think it's confusing to only have a subset of import statements provided.
But then again, the missing ones will be resolved without confusion
(hopefully) ;) We can go with this and see what feedback we get.

(Just doing it for some examples sounds reasonable.)

=E2=80=93 Ufuk

On Thu, Nov 19, 2015 at 5:29 PM, Robert Metzger <rmetzger@apache.org> wrote=
:

> Thank you for the feedback.
>
> I was also spending some time thinking about automating this, but I don't
> have the time right now to bring the required infrastructure in place.
>
> For now, I'll just add import statements for classes with the potential o=
f
> confusion (in particular between the Scala and Java API, Hadoop/Flink
> classes, ..)
> Also, I'll not add the import statements to ALL examples, only to those
> where people might copy paste them.
> Please -1 me if you are against this, otherwise, I'll soon open a PR.
>
>
> On Wed, Nov 18, 2015 at 5:04 PM, Nick Dimiduk <ndimiduk@gmail.com> wrote:
>
> > In HBase we keep an hbase-examples module with working code. Snippets
> from
> > that module are pasted into docs and referenced. Yes, we do see
> divergence,
> > especially when refactor tools are involved. I once looked into a doc
> tool
> > for automatically extracting snippets from source code, but that turned
> > into a rat-hole and didn't pursue it further. Maybe tooling has improve=
d
> > since then?
> >
> > On Wednesday, November 18, 2015, Maximilian Michels <mxm@apache.org>
> > wrote:
> >
> > > Hi Robert.
> > >
> > > Good suggestion. Generally, it would be nice to have complete code
> > > examples available in the documentation. Even better, a way to only
> > > show excerpts of the complete example with the option of copying the
> > > complete working example.
> > >
> > > For instance:
> > >
> > > public Example {
> > >    public static void main(String[] args) {
> > >        ExecutionEnvironment env =3D ...
> > >
> > >        // BEGIN: example
> > >        env.fromElements(1,2,3,4)
> > >        env.map(element -> element * 2)
> > >        // END: example
> > >
> > >        env.print();
> > >    }
> > > }
> > >
> > > This still poses the problem that we need to run those examples in an
> > > automated way to ensure they are actually working.
> > >
> > > Cheers,
> > > Max
> > >
> > > On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <rmetzger@apache.org
> > > <javascript:;>> wrote:
> > > > Hi,
> > > >
> > > > I helped somebody yesterday on SO [1] who had issues with the Scala
> API
> > > > because he was importing the classes from the Java API.
> > > > Somebody else complained about this issue as well in the comments
> below
> > > the
> > > > documentation [2], and I think both users are right: Its an
> unnecessary
> > > > obstacle when learning Flink that users have to figure out which
> class
> > to
> > > > import.
> > > >
> > > > How about adding import statements to the examples?
> > > > Is there a nicer way of solving the problem?
> > > >
> > > >
> > > > Regards,
> > > > Robert
> > > >
> > > >
> > > >
> > > > [1] http://stackoverflow.com/a/33721528/568695
> > > > [2]:
> > > >
> > >
> >
> https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streami=
ng_guide.html#comment-2365998014
> > >
> >
>

--001a11c3cc8e9bf8710524e83b85--