diff --git a/README.todo b/README.todo index 92a128e..c8f21b7 100644 --- a/README.todo +++ b/README.todo @@ -1,26 +1,25 @@ -TODO -==== -Todo tasks can be found in the bug tracker at http://easejs.org/bugs. Below is -a list of the glaring issues that may be found at first glance. +# -*-org-*- +# TITLE: GNU ease.js TODOs + +TODO tasks can be found in the bug tracker at +http://easejs.org/bugs. Below is a list of the glaring issues that may +be found at first glance. -COUPLING --------- -During the beginning of the project, all modules were represented as object -literals, which is similar to the concept of a Singleton. This satisfied the -needs of the early project, but it soon evolved far past its original design and -resulted in a tightly coupled system that was difficult to maintain, add to and -test. Refactoring into prototypes is ongoing. +* TODO Coupling + During the beginning of the project, all modules were represented as + object literals, which is similar to the concept of a + Singleton. This satisfied the needs of the early project, but it + soon evolved far past its original design and resulted in a tightly + coupled system that was difficult to maintain, add to and + test. Refactoring into prototypes is ongoing. +* TODO Performance tests + Performance tests need to be written for every aspect of the + system. They will ultimately be graphed to show the relative + performance across versions of the software. -PERFORMANCE TESTS ------------------ -Performance tests need to be written for every aspect of the system. They will -ultimately be graphed to show the relative performance across versions of the -software. - - -CLOSURE COMPILER WARNINGS -------------------------- -Certain warnings are suppressed. Figure out the best way to resolve them without -suppressing them, unless suppression is truely the best option. +* TODO Closure compiler warnings + Certain warnings are suppressed. Figure out the best way to resolve + them without suppressing them, unless suppression is truely the best + option. diff --git a/README.traits b/README.traits index 437da55..772978a 100644 --- a/README.traits +++ b/README.traits @@ -1,98 +1,88 @@ -GNU ease.js Traits -================== +# -*-org-*- +# TITLE: GNU ease.js Traits + The trait implementation is not yet complete; this is the list of known -issues/TODOs. If you discover any problems, please send an e-mail to +issues/TODOs. If you discover any problems, please send an e-mail to bug-easejs@gnu.org. Aside from the issues below, traits are stable and ready to be used in -production. See the test cases and performance tests for more information -and a plethora of examples until the documentation is complete. +production. See the test cases and performance tests for more +information and a plethora of examples until the documentation is +complete. -TODO: Trait Extending ---------------------- -Currently, the only way for a trait to override methods of a class it is -being mixed into is to implement a common interface. Traits should -alternatively be able to "extend" classes, which will have effects similar -to Scala in that the trait can only be mixed into that class. Further, -traits should be able to extend and mix in other traits (though such should -be done conservatively). +* TODO Trait Extending + Currently, the only way for a trait to override methods of a class + it is being mixed into is to implement a common interface. Traits + should alternatively be able to "extend" classes, which will have + effects similar to Scala in that the trait can only be mixed into + that class. Further, traits should be able to extend and mix in + other traits (though such should be done conservatively). +* TODO Documentation + Due to the trait implementation taking longer than expected to + complete, and the importance of the first GNU release, trait + documentation is not yet complete. Instead, traits have been + released as a development preview, with the test cases and + performance tests serving as interim documentation. -TODO: Documentation -------------------- -Due to the trait implementation taking longer than expected to complete, and -the importance of the first GNU release, trait documentation is not yet -complete. Instead, traits have been released as a development preview, with -the test cases and performance tests serving as interim documentation. + Comprehensive documentation, including implementation details and + rationale, will be available shortly. -Comprehensive documentation, including implementation details and rationale, -will be available shortly. +* TODO Static members + Static members are currently unsupported. There is no particular + difficulty in implementing them---the author didn't want it to hold + up an initial release (the first GNU release) even further. +* TODO Getters/setters + Getters and setters, although they act like properties, should be + treated as though they are methods. Further, they do not suffer + from the same complications as properties, because they are only + available in an ES5 environment (as an ECMAScript language feature). -TODO: Static members --------------------- -Static members are currently unsupported. There is no particular difficulty -in implementing them---the author didn't want it to hold up an initial -release (the first GNU release) even further. +* TODO Mixin Caching + The pattern =Type.use(...)(...)=---that is, mix a trait into a class + and immediate instantiate the result---is a common idiom that can + often be better for self-documentation than storing the resulting + class in another variable before instantiation. Currently, it's also + a terrible thing to do in any sort of loop, as it re-mixes each and + every time. + We should introduce a caching system to avoid that cost and make it + fairly cheap to use such an idiom. Further, this would permit the + Scala-like ability to use Type.use in Class.isA checks. -TODO: Getters/setters ---------------------- -Getters and setters, although they act like properties, should be treated as -though they are methods. Further, they do not suffer from the same -complications as properties, because they are only available in an ES5 -environment (as an ECMAScript language feature). +* TODO Public/Protected Property Support + Private properties are currently supported on traits because they do + not affect the API of the type they are mixed into. However, due to + limitations of pre-ES5 environments, implementing public and + protected member epoxying becomes ugly in the event of a fallback, + amounting essentially to re-assignment before/after trait method + proxying. It is possible, though. + This is not a necessary, or recommended, feature---one should aim to + encapsulate all data, not expose it---but it does have its + legitimate uses. As such, this is not a high-priority item. -TODO: Mixin Caching -------------------- -The pattern Type.use(...)(...)---that is, mix a trait into a class and -immediate instantiate the result---is a common idiom that can often be -better for self-documentation than storing the resulting class in another -variable before instantiation. Currently, it's also a terrible thing to do -in any sort of loop, as it re-mixes each and every time. +* TODO Trait-specific error messages + All error messages resulting from traits should refer to the trait + by name and any problem members by name, and should offer + context-specific suggestions for resolution. Currently, the errors + may be more general and may reflect the internal construction of + traits, which will be rather confusing to users. -We should introduce a caching system to avoid that cost and make it fairly -cheap to use such an idiom. Further, this would permit the Scala-like -ability to use Type.use in Class.isA checks. +* TODO Performance enhancements + The current trait implementation works well, but is relatively slow + (compared to how performant it could be). While this is sufficient + for most users' uses, there is plenty of room for + improvement. Until that time, be mindful of the performance test + cases in the =test/perf= directory. +* TODO Intermediate object as class + The immediate syntax---=Foo.use(T)()=---is a short-hand equivalent + of =Foo.use(T).extend({})()=. As such, for consistency, =Class.isA= + should consider the intermediate object returned by a call to =use= + to be a class. -TODO: Public/Protected Property Support ---------------------------------------- -Private properties are currently supported on traits because they do not -affect the API of the type they are mixed into. However, due to limitations -of pre-ES5 environments, implementing public and protected member epoxying -becomes ugly in the event of a fallback, amounting essentially to -re-assignment before/after trait method proxying. It is possible, though. - -This is not a necessary, or recommended, feature---one should aim to -encapsulate all data, not expose it---but it does have its legitimate uses. -As such, this is not a high-priority item. - - -TODO: Trait-specific error messages ------------------------------------ -All error messages resulting from traits should refer to the trait by name -and any problem members by name, and should offer context-specific -suggestions for resolution. Currently, the errors may be more general and -may reflect the internal construction of traits, which will be rather -confusing to users. - - -TODO: Performance enhancements ------------------------------- -The current trait implementation works well, but is relatively slow -(compared to how performant it could be). While this is sufficient for most -users' uses, there is plenty of room for improvement. Until that time, be -mindful of the performance test cases in the `test/perf' directory. - - -TODO: Intermediate object as class ----------------------------------- -The immediate syntax---Foo.use(T)()---is a short-hand equivalent of -Foo.use(T).extend({})(). As such, for consistency, Class.isA should consider -the intermediate object returned by a call to `use' to be a class. - -If we are to do so, though, we must make sure that the entire class API is -supported. + If we are to do so, though, we must make sure that the entire class + API is supported.