More CanJS documentation remarks


#1

My previous remarks about DoneJS documentation were so well received I’m encouraged to share a bit more :grinning:. Note that all of the following is based on the 5.0.0.pre.0 docs:

Today I was attempting to understand this code* in an example from the 5.0.0.pre.0 API doc on can-component documentation:

var ViewModel = DefineMap.extend({
	// Contains a list of all panel scopes within the
	// tabs element.
	panels: {
		Default: PanelList.extend({})
	},
	active: {
		Type: Panel
	},
...

So I performed a CanJS native search for the term DefineMap.extend and found nothing (search issue already covered in my previous post). Then I searched for DefineMap and landed on this page about Map, which gave the terse description:

Specify the type of the DefineMap that should be instantiated by the connection.

That explanation wasn’t sufficient so I clicked on the word DefineMap contained in it, which caused this page describing can-define/map/map to appear. The beginning of the page reads,

new DefineMap([props])

The can-define/map/map module exports the DefineMap constructor function.

Calling new DefineMap(props) creates a new instance of DefineMap or an extended DefineMap. Then, assigns every property on props to the new instance. If props are passed that are not defined already, those property definitions are created. If the instance should be sealed, it is sealed.

I’m sure this makes sense as a reference to those already versed in DefineMap, but it’s not helpful to me as it uses terms I don’t yet understand (including DefineMap!). The rest of this page isn’t much better; the most general explanation I found was,

can-define/map/map is used to create easily extensible observable types with well defined behavior.

But I don’t know what easily extensible observable type or well defined behavior mean and am also puzzled that DefineMap is apparently being referred to as can-define/map/map.

Following another result from my above search, I read the can/map documentation. It is a bit more generalized and useful, but still doesn’t answer my original question, What is DefineMap?

By browsing the CanJS documentation site I eventually discovered the section Key-Value Observables, under Technology Overview. Here, I find a generalized explanation which if I read it enough times I think I will finally understand, and which in turn will serve as a key to the rest of the CanJS documentation.

But the Technology Overview doesn’t come up when I use the CanJS documentation page’s search for DefineMap! I would argue that it should, and that the words observable objects at the top of the can-define/map/map page should link to Key-Value Observables in the crucial Technology Overview document. That would quickly direct newbies like me to this vital information (and stop us from bugging you so you can spend more time coding!)


*BTW, for me the code creates an Add vegetables button that doesn’t do anything. I assume the example is still “beta” and am trying to make it work as an exercise.


#2

@code-read, thank you so much for taking the time to write this up! It is very very appreciated and absolutely not a bother!

You’re right that the descriptions of the main packages aren’t that great; for can-define/map/ in particular, that description doesn’t give you much info at all. :sweat_smile: I have an issue open for that, and your suggestion to link to other docs is a good one.

[BTW, not saying you have to do this, but I want to point out: on each canjs.com page there’s an Edit on GitHub link, which makes it easier to submit pull requests to fix things in the docs. If you were so inclined as to submit a PR to add a link in that description, we’d get it merged in, otherwise I will later today. :smile:]

Also, thanks for pointing out that broken tabs demo, I think I can get that fixed today.

One way we’re going to fix some of the issues you brought up is by updating all the package titles to their more common name in CanJS 5.

[For some backstory… in CanJS 3 & 4 we encourage everyone to use the individual packages, like can-define. This is more difficult to get started with, so we added a module that exports the packages by the name we commonly use in the docs, e.g. import DefineMap from "can/es" instead of import DefineMap from "can-define/map/map". This’ll be the default in CanJS 5, so we’ll update the site to show those names instead (which I think would solve the issue of not being able to search for DefineMap and get the right docs). The More You Know.™ :rainbow::star:️]

After we get CanJS 5 out the door, we’re going to turn our attention towards fixing a bunch of things in the docs (that was one of the most highly-voted items in our last community survey).

One more thing in this lengthy post… some more resources to help you get started: if you haven’t already, I’d recommend checking out the Chat and TodoMVC guides, then looking through the different recipes. If you’re more of a “read the API docs” kind of guy, then the can-define/map/ (and PropDefinition) docs will get you started with observables, the can-stache docs will get you started with templates, and the can-component (and especially ViewModel docs will help tie those together. :smiley: