This page is no longer maintained — Please continue to the home page at www.scala-lang.org

complexity annotations

5 replies
Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
This one was inspired by javaposse...
How about adding some annotations, possibly only to scaladoc, that let an API designer suggest guidelines for usage.Indicating what's considered to be the heart of the API for most normal usage, what's less common, and what's only supplied to support "expert" usage
The basic idea is that this information can then be used to filter/organise code completion and scaladoc, helping guide developers in what will be (for many) both a new language and new libraries.
Ideas might be @primary, @secondary, @tertiary or @basic, @advanced, @expertThe default level to be determined via this forum :)
rlemaire
Joined: 2009-11-06,
User offline. Last seen 2 years 46 weeks ago.
Re: complexity annotations
Hi,

Wouldn't it be a bit duplicated with visibility/encapsulation ? If a feature must not be used it should not be visible.

Scala provide a more flexible visibility system than java, one can hide almost every thing to the client code, except what is really needed by the client code and intended to be use.

An API (like every piece of software) must be as simple as possible. There should be no place for several levels of usage.
--
Raphaël Lemaire


On Sat, Dec 12, 2009 at 21:29, Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com> wrote:
This one was inspired by javaposse...
How about adding some annotations, possibly only to scaladoc, that let an API designer suggest guidelines for usage. Indicating what's considered to be the heart of the API for most normal usage, what's less common, and what's only supplied to support "expert" usage
The basic idea is that this information can then be used to filter/organise code completion and scaladoc, helping guide developers in what will be (for many) both a new language and new libraries.
Ideas might be @primary, @secondary, @tertiary or @basic, @advanced, @expertThe default level to be determined via this forum :)

Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: complexity annotations
This isn't about hiding anything, or compiler-enforced restrictions.
It's about an API designer being able to say "THIS method, yes, this one here, this is the one I imagined a client using 99% of the time, look at this one first to see if it what you want before plunging into the rest of the documentation", and also be able to say "it's VERY unlikely you'll want to use this other method, probably only 3 people in the world are doing anything weird enough to need it, so it's almost certainly not what you want"

2009/12/13 Raphaël Lemaire <lemaire [dot] raphael [at] gmail [dot] com>
Hi,

Wouldn't it be a bit duplicated with visibility/encapsulation ? If a feature must not be used it should not be visible.

Scala provide a more flexible visibility system than java, one can hide almost every thing to the client code, except what is really needed by the client code and intended to be use.

An API (like every piece of software) must be as simple as possible. There should be no place for several levels of usage.
--
Raphaël Lemaire


On Sat, Dec 12, 2009 at 21:29, Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com> wrote:
This one was inspired by javaposse...
How about adding some annotations, possibly only to scaladoc, that let an API designer suggest guidelines for usage. Indicating what's considered to be the heart of the API for most normal usage, what's less common, and what's only supplied to support "expert" usage
The basic idea is that this information can then be used to filter/organise code completion and scaladoc, helping guide developers in what will be (for many) both a new language and new libraries.
Ideas might be @primary, @secondary, @tertiary or @basic, @advanced, @expertThe default level to be determined via this forum :)


rlemaire
Joined: 2009-11-06,
User offline. Last seen 2 years 46 weeks ago.
Re: complexity annotations
I understand it this way at the first place.

Maybe if it's very unlikely that people use it (3 in the world ...) it should not be here. It just make the API's interface more complex.


Can you give an example of an API where a method does something that can't be done with the other ones and is needed for special cases ?
--
Raphaël Lemaire

2009/12/13 Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com>
This isn't about hiding anything, or compiler-enforced restrictions.
It's about an API designer being able to say "THIS method, yes, this one here, this is the one I imagined a client using 99% of the time, look at this one first to see if it what you want before plunging into the rest of the documentation", and also be able to say "it's VERY unlikely you'll want to use this other method, probably only 3 people in the world are doing anything weird enough to need it, so it's almost certainly not what you want"

2009/12/13 Raphaël Lemaire <lemaire [dot] raphael [at] gmail [dot] com>
Hi,

Wouldn't it be a bit duplicated with visibility/encapsulation ? If a feature must not be used it should not be visible.

Scala provide a more flexible visibility system than java, one can hide almost every thing to the client code, except what is really needed by the client code and intended to be use.

An API (like every piece of software) must be as simple as possible. There should be no place for several levels of usage.
--
Raphaël Lemaire


On Sat, Dec 12, 2009 at 21:29, Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com> wrote:
This one was inspired by javaposse...
How about adding some annotations, possibly only to scaladoc, that let an API designer suggest guidelines for usage. Indicating what's considered to be the heart of the API for most normal usage, what's less common, and what's only supplied to support "expert" usage
The basic idea is that this information can then be used to filter/organise code completion and scaladoc, helping guide developers in what will be (for many) both a new language and new libraries.
Ideas might be @primary, @secondary, @tertiary or @basic, @advanced, @expertThe default level to be determined via this forum :)



dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: complexity annotations
I can give you a counter-example. All of the methods on Traversable can be done with "foreach". That's not a good reason to require every application to rely solely on that method, however.
Moreover, whenever you transfer the responsibility for one such methods to the application, you break the proper layering of responsibilities. It's Traversable's responsibility to handle Traversable's -- the application should be concerned with other things.
But, to an example of where layering would apply, let's consider Actor. The basic API for them are:
!!?actreactreceive start
That handles most usage. On a second level, we have
!!reactWithinreceiveWithin
Those handles a few cases not covered by the first level, not needed by most applications but still basic for those apps that require them.
On a third level, there is stuff that provide more advanced actors setups:
?linkreceiversendtrapExitunlink
If the documentation was layered that way, it would improve usability for those who are learning -- at the cost of making alphabetic order unavailable to those who want just to check a minor detail. OTOH, the latter would be better served by direct method search.

2009/12/13 Raphaël Lemaire <lemaire [dot] raphael [at] gmail [dot] com>
I understand it this way at the first place.

Maybe if it's very unlikely that people use it (3 in the world ...) it should not be here. It just make the API's interface more complex.


Can you give an example of an API where a method does something that can't be done with the other ones and is needed for special cases ?
--
Raphaël Lemaire

2009/12/13 Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com>
This isn't about hiding anything, or compiler-enforced restrictions.
It's about an API designer being able to say "THIS method, yes, this one here, this is the one I imagined a client using 99% of the time, look at this one first to see if it what you want before plunging into the rest of the documentation", and also be able to say "it's VERY unlikely you'll want to use this other method, probably only 3 people in the world are doing anything weird enough to need it, so it's almost certainly not what you want"

2009/12/13 Raphaël Lemaire <lemaire [dot] raphael [at] gmail [dot] com>
Hi,

Wouldn't it be a bit duplicated with visibility/encapsulation ? If a feature must not be used it should not be visible.

Scala provide a more flexible visibility system than java, one can hide almost every thing to the client code, except what is really needed by the client code and intended to be use.

An API (like every piece of software) must be as simple as possible. There should be no place for several levels of usage.
--
Raphaël Lemaire


On Sat, Dec 12, 2009 at 21:29, Kevin Wright <kev [dot] lee [dot] wright [at] googlemail [dot] com> wrote:
This one was inspired by javaposse...
How about adding some annotations, possibly only to scaladoc, that let an API designer suggest guidelines for usage. Indicating what's considered to be the heart of the API for most normal usage, what's less common, and what's only supplied to support "expert" usage
The basic idea is that this information can then be used to filter/organise code completion and scaladoc, helping guide developers in what will be (for many) both a new language and new libraries.
Ideas might be @primary, @secondary, @tertiary or @basic, @advanced, @expertThe default level to be determined via this forum :)






--
Daniel C. Sobral

I travel to the future all the time.
bjohanns
Joined: 2009-10-23,
User offline. Last seen 1 year 37 weeks ago.
Re: complexity annotations

Hi

+1 to that.

Some simple annotation/markup would enable API-doc-generators to compile a
sort of "conceptional" index list for a given API documentation.

This wouldn't replace a good introduction but could assist the "non-expert" /
casual API-user in selecting the right method. So if I am ending up using the
"expert" stuff for something trivial I'm at least warned that I'm probably
doing something wrong...

As introductions take their time to write (especially good ones) they are
often missing. So I hope that a simple doc-annotation could improve the
situation to some extend.

Greetings
Bernd

Am Sonntag, 13. Dezember 2009 14:04:34 schrieb Daniel Sobral:
> I can give you a counter-example. All of the methods on Traversable can be
> done with "foreach". That's not a good reason to require every application
> to rely solely on that method, however.
>
> Moreover, whenever you transfer the responsibility for one such methods to
> the application, you break the proper layering of responsibilities. It's
> Traversable's responsibility to handle Traversable's -- the application
> should be concerned with other things.
>
> But, to an example of where layering would apply, let's consider Actor. The
> basic API for them are:
>
> !
> !?
> act
> react
> receive
> start
>
> That handles most usage. On a second level, we have
>
> !!
> reactWithin
> receiveWithin
>
> Those handles a few cases not covered by the first level, not needed by
> most applications but still basic for those apps that require them.
>
> On a third level, there is stuff that provide more advanced actors setups:
>
> ?
> link
> receiver
> send
> trapExit
> unlink
>
> If the documentation was layered that way, it would improve usability for
> those who are learning -- at the cost of making alphabetic order
> unavailable to those who want just to check a minor detail. OTOH, the
> latter would be better served by direct method search.
>
>
> 2009/12/13 Raphaël Lemaire
>
> > I understand it this way at the first place.
> >
> > Maybe if it's very unlikely that people use it (3 in the world ...) it
> > should not be here. It just make the API's interface more complex.
> >
> >
> > Can you give an example of an API where a method does something that
> > can't be done with the other ones and is needed for special cases ?
> > --
> > Raphaël Lemaire
> >
> > 2009/12/13 Kevin Wright
> >
> > This isn't about hiding anything, or compiler-enforced restrictions.
> >
> >> It's about an API designer being able to say "THIS method, yes, this one
> >> here, this is the one I imagined a client using 99% of the time, look at
> >> this one first to see if it what you want before plunging into the rest
> >> of the documentation", and also be able to say "it's VERY unlikely
> >> you'll want to use this other method, probably only 3 people in the
> >> world are doing anything weird enough to need it, so it's almost
> >> certainly not what you want"
> >>
> >>
> >> 2009/12/13 Raphaël Lemaire
> >>
> >> Hi,
> >>
> >>> Wouldn't it be a bit duplicated with visibility/encapsulation ? If a
> >>> feature must not be used it should not be visible.
> >>>
> >>> Scala provide a more flexible visibility system than java, one can hide
> >>> almost every thing to the client code, except what is really needed by
> >>> the client code and intended to be use.
> >>>
> >>> An API (like every piece of software) must be as simple as possible.
> >>> There should be no place for several levels of usage.
> >>> --
> >>> Raphaël Lemaire
> >>>
> >>>
> >>>
> >>> On Sat, Dec 12, 2009 at 21:29, Kevin Wright <
> >>>
> >>> kev [dot] lee [dot] wright [at] googlemail [dot] com> wrote:
> >>>> This one was inspired by javaposse...
> >>>>
> >>>> How about adding some annotations, possibly only to scaladoc, that let
> >>>> an API designer suggest guidelines for usage.
> >>>> Indicating what's considered to be the heart of the API for most
> >>>> normal usage, what's less common, and what's only supplied to support
> >>>> "expert" usage
> >>>>
> >>>> The basic idea is that this information can then be used to
> >>>> filter/organise code completion and scaladoc, helping guide developers
> >>>> in what will be (for many) both a new language and new libraries.
> >>>>
> >>>> Ideas might be @primary, @secondary, @tertiary or @basic, @advanced,
> >>>> @expert
> >>>> The default level to be determined via this forum :)
>

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland