flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ufuk Celebi <...@apache.org>
Subject Re: [DISCUSS] Include import statements in documentation code examples
Date Thu, 19 Nov 2015 17:38:14 GMT
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.)

– 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 of
> 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 improved
> > 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 = ...
> > >
> > >        // 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/streaming_guide.html#comment-2365998014
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message