New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Show inherited and mixed-in values #4496

Open
justinbmeyer opened this Issue Sep 28, 2018 · 5 comments

Comments

Projects
None yet
4 participants
@justinbmeyer
Copy link
Contributor

justinbmeyer commented Sep 28, 2018

TLDR; Many parts of CanJS get inherited or mixed-in methods and behaviors. Lets make it easier for users to understand what is mixed in.

This was discussed on a recent live stream (35:33) and a previous live stream.

The problem

DefineMap, observe.Object, SimpleMap, CanMap and their list-variants all mixin https://canjs.com/doc/can-event-queue/map/map.html. Most things also inherit from Construct.

In DefineMap, these are documented here: https://canjs.com/doc/can-define/map/map.html#Mixed_ininstancemethodsandproperties

But this isn't super obvious. And, it is difficult to make work. It relies on some special knowledge of bit-docs:

{{#each (getChildren [can-event-queue/map/map])}}
- [{{name}}] - {{description}}{{/each}}

The Solution

The solution is to make it easy for a module to specify what is mixed in and what is inherited. Perhaps:

@mixin can-event-queue/map/map can-define/map/map.prototype
@inherits can-construct

Display Ideas

Idea A - just list inherited and mixed package at the top.

Here's how JavaDoc shows inheritance and what is mixed-in:

image

image

Idea B - Have an area after signatures that list everything mixed-in

image

Idea C - List mixed/inherited in stuff in the sidebar

Here you could click to expand what is inherited by can-construct and can-event-queue/map/map:

image

Ideally, the methods/symbols would replace those links.

Idea D - Buttons to expand what's mixed-in / inherited

image

@eben-roux

This comment has been minimized.

Copy link
Contributor

eben-roux commented Oct 6, 2018

Depending on how deep such a hierarchy goes the documentation may become quite long. Perhaps having the display of the "extended" documentation as an option would be useful.

@frank-dspeed

This comment has been minimized.

Copy link
Contributor

frank-dspeed commented Oct 20, 2018

@justinbmeyer i think reading this up will give some interesting infos about why prototype stuff should get not used as much !

https://mathiasbynens.be/notes/prototypes

@justinbmeyer

This comment has been minimized.

Copy link
Contributor

justinbmeyer commented Oct 20, 2018

@frank-dspeed I don’t think anything in that document states one shouldn’t use prototypes. They are heavily optimized for. CanJS doesn’t do patterns that invalidate these optimizations.

@justinbmeyer

This comment has been minimized.

Copy link
Contributor

justinbmeyer commented Oct 20, 2018

Specifically:

Or if you really need to touch prototypes, then do it before other code runs, so that you at least don’t invalidate all the optimizations in the engine while your code is running.

Canjs doesn’t touch native prototypes. And, these mixins are added to types before any instance is created. There’s no performance issue.

@frank-dspeed

This comment has been minimized.

Copy link
Contributor

frank-dspeed commented Oct 21, 2018

@justinbmeyer i would love when we could get away from mixin style to some more functional style. so that all is more predictable even without documentation i like really much the longCamelCaseNamesForFunctionsThatTellPeopleExactlyWhatTheyDo but ok it has nothing to do with this issue so lets forget about that :)

@chasenlehara chasenlehara changed the title Proposal: Show inherited and mixed in values Proposal: Show inherited and mixed-in values Nov 16, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment