<div dir="ltr">Thanks Phil for the explanation.<div><br></div><div>Cheers, Peter</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Aug 4, 2015 at 5:20 AM, Phil (list) <span dir="ltr"><<a href="mailto:pbpublist@gmail.com" target="_blank">pbpublist@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On Mon, 2015-08-03 at 22:35 +0200, Peter van Rooijen wrote:<br>
> Hi,<br>
><br>
><br>
> 1. I'm totally against introducing pragma's (perhaps they already<br>
> exist in Cuis, I don't know).<br>
><br>
<br>
</span>Too late, they're already there (VM functionality)<br>
<div><div class="h5"><br>
><br>
> First of all because they are not Smalltalk, and second because they<br>
> are not needed.<br>
><br>
><br>
> What would be wrong with simply introducing a convention and adding a<br>
> method cuisPublicSelectors to a class?<br>
><br>
><br>
> To avoid seeing them on the instance side, there could also be<br>
> cuisPublicInstanceSelectors and cuisPublicClassSelectors on the class<br>
> side.<br>
><br>
><br>
> At the top these would be defined as self allSelectors.<br>
><br>
><br>
> If someone wanted to view only the public selectors in a browser, they<br>
> would check the checkbox for that and the browser would hide the<br>
> non-public selectors.<br>
><br>
><br>
> Or the browser could show a nice public interface report added to the<br>
> class comment.<br>
><br>
><br>
> 2. On another point: interfaces such as indexable could simply be<br>
> described by creating a class CuisInterfaceSpecification which gets a<br>
> subclass for each interface specified. The methods belonging to the<br>
> interface are defined and get a comment explaining the semantics of<br>
> the method. This makes it easy for tools to check which interfaces are<br>
> (probably) implemented by a class. If desired, each method could be<br>
> additionally defined to return a MethodSpecification object that knows<br>
> about preconditions, invariants, return values, argument and return<br>
> types/interfaces...but then it becomes progressively more complicated.<br>
><br>
><br>
> But anyway, in this way whoever thinks it's important enough, can add<br>
> the info (for public selectors of a class or for whole interface<br>
> specifications) without anyone who is not interested in that needing<br>
> to know or care about that.<br>
><br>
<br>
</div></div>This is too complicated for what I think we're trying to achieve...<br>
<span class=""><br>
><br>
> In my mind that gels well with Cuis' philosophy of simplicity. But I<br>
> could be missing the whole point...<br>
><br>
<br>
</span>The intent (what I was going for at least) is to provide a means for<br>
Juan and anyone else modifying the core image / packages to have a<br>
bidirectional communications channel with anyone looking to have a<br>
stable set of APIs that they can depend on. It needs to be something<br>
that's simple and easy for both Juan and us to use, or it won't get<br>
used. I think that Juan's pragma approach accomplishes this. All it<br>
signals is that 'this method will keep working as it currently does<br>
until/unless it is formally decided to change it'.<br>
<br>
So here's an example of how this might work:<br>
1) Let's say we propose that #asString as a public API and Juan agrees<br>
that this is a useful method and should be fairly stable.<br>
Implementations of #asString get marked with a publicAPI (or whatever<br>
name makes sense) pragma<br>
2) Those of us who care can then work to ensure that our code is using<br>
these publicAPI methods when possible. This will also help drive out<br>
some of our own bad behavior where we were calling things that we really<br>
shouldn't have been.<br>
3) Time passes and life is good :-)<br>
4) Down the line (Cuis 5.x, 6.x... whatever) Juan decides that #asString<br>
needs to change (who knows... unicode support... or maybe he just<br>
decides that #asString is the wrong way to do it) Seeing that #asString<br>
is flagged publicAPI, he knows not to 'just do it' but rather make sure<br>
that the change gets called out in the release notes (after some mailing<br>
list discussion if he deems it worthwhile to do so... his call) and that<br>
since it will likely break code to probably wait for a major release.<br>
<br>
This also allows for deprecating things that are designated as<br>
publicAPI... just because something is public does not mean it always<br>
will be, just that the changes to things that are need to be<br>
communicated more richly. For me, the documentation aspect of it is a<br>
nice to have secondary objective that falls out of it... getting to a<br>
stable core is the primary objective. (i.e. we're not documenting for<br>
the sake of documenting)<br>
<div class="HOEnZb"><div class="h5"><br>
><br>
> Cheers, Peter<br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
> On Mon, Aug 3, 2015 at 9:19 PM, Phil (list) <<a href="mailto:pbpublist@gmail.com">pbpublist@gmail.com</a>><br>
> wrote:<br>
> On Mon, 2015-08-03 at 15:49 -0300, Juan Vuletich wrote:<br>
> > Hi Doug,<br>
> ><br>
> > On 8/2/2015 4:04 AM, Douglas Brebner wrote:<br>
> > > On 19/07/2015 22:38, Phil (list) wrote:<br>
> > >> Ready to go... we just need to agree on how to do it<br>
> (pragma/method<br>
> > >> call/method category/method name?) Also, this is most<br>
> definitely<br>
> > >> related to the 'Canonical test cases?' thread from a few<br>
> months ago<br>
> > >> as these types of test cases / docs are part of the<br>
> backfill I was<br>
> > >> referring to.<br>
> > ><br>
> > > I vaguely recall that many years ago there was a project<br>
> called<br>
> > > SmallInterfaces that let you define public interfaces to<br>
> objects. (Or<br>
> > > something like that). Would that be a good way to document<br>
> the<br>
> > > public/private api using code?<br>
> > ><br>
> > > (sorry for being so vague but I've been awake for 24+<br>
> hours now)<br>
> ><br>
> > Thanks for the pointer. I took a look at it. It is quite<br>
> like Java<br>
> > interfaces. The tools are interesting. But I see several<br>
> downsides:<br>
> ><br>
> > - Each interface is a class. Each method in the protocol is<br>
> an actual<br>
> > method. If we use this to document all public protocols in<br>
> Cuis, it<br>
> > would mean a lot of new classes and methods.<br>
> > - The source code of (for example) OrderedCollection>>at:<br>
> would not<br>
> > include the information of it belonging to interface<br>
> "Indexable".<br>
> > Without additional support from tools users can't tell<br>
> whether a message<br>
> > is public protocol or not. And the base image / package<br>
> maintainer can't<br>
> > easily see he's about to change a public api.<br>
> ><br>
> > I think a method pragma, that includes the name of the<br>
> protocol avoids<br>
> > these issues and is a better choice.<br>
> ><br>
><br>
><br>
> I agree. Let's keep it as simple as possible and see how far<br>
> that gets<br>
> us.<br>
><br>
> > Cheers,<br>
> > Juan Vuletich<br>
> ><br>
> > _______________________________________________<br>
> > Cuis mailing list<br>
> > <a href="mailto:Cuis@jvuletich.org">Cuis@jvuletich.org</a><br>
> > <a href="http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org" rel="noreferrer" target="_blank">http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Cuis mailing list<br>
> <a href="mailto:Cuis@jvuletich.org">Cuis@jvuletich.org</a><br>
> <a href="http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org" rel="noreferrer" target="_blank">http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Cuis mailing list<br>
> <a href="mailto:Cuis@jvuletich.org">Cuis@jvuletich.org</a><br>
> <a href="http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org" rel="noreferrer" target="_blank">http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org</a><br>
<br>
<br>
<br>
_______________________________________________<br>
Cuis mailing list<br>
<a href="mailto:Cuis@jvuletich.org">Cuis@jvuletich.org</a><br>
<a href="http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org" rel="noreferrer" target="_blank">http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org</a><br>
</div></div></blockquote></div><br></div>