Documentation Issues

[justinbmeyer]

can-define

• [ ] Needs a purpose section.
• [ ] Probably could show use of [can-observation].

can-define.types.html

• [x] codepen-able ES6 examples
• [x] Links to can-define-types.

can-define.types.propDefinition.html

• [x] @codepen examples
• [x] default option shows the old value.
• [ ] type should give a hint at what should be done.
• [ ] serialize might want to show false option.
• [ ] identity might want to reference that this is used by can-reflect.getSchema and the models.
• [ ] String -> needs an example
• [ ] function() Array GETTER - needs better examples
• [x] Code following "Within a property definition," isn't js.
• [ ] Might want to specify order -> TYPE -> SETTER -> GETTER. Also how default() will use the type.

can-define.types.valueOptions.html

• [ ] ValueOptions doesn't really say what it relates to. No description.
• [ ] Nothing in signature.
• [ ] Needs to be code-penable.

can-define.types.default.html

• [ ] defined on demand (lazily)
• [ ] might want to talk about how these will go through type and set. (
• [x] codepen

can-define.types.defaultConstructor.html

• [ ] Use section should explain what it's doing
• [x] codepen

can-define.types.get.html

• [ ] read on a define map
• [ ] like can-observation
• [ ] might want to say DON'T set state in a get()
• [ ] is the shorthand mentioned?
• [ ] Typically, lastSetValue should be an observable value, like a can-compute or promise. If it's not, it's likely that a set should be used instead. Is this accurate?
• [ ] Why "virtual properties"? Maybe computed properties?
• [ ] might want to mention value as the place where get() isn't able to derive the value.
• [x] codepen examples
• [ ] complete review (I, justinbmeyer, has not completed it)

[indifferentghost]

can-define.types.identity.html

• [x] Boolean needs codepen-able examples that log the result.
• [ ] Use doesn't show a model case. Link to examples elsewhere.

can-define.types.serialize.html

• [x] Boolean should have an example to go along with it

This can be used for many reasons, including saving a can-connected instance on the server or serializing [can-route.map can-route.map]'s internal map for display in the hash or pushstate URL.

• [x] Use's first paragraph was probably meant to be a link. can-route.map -> can-route.data
• [x] Use examples should be codepen-able and relavent examples.
• [x] The first example in Use probably doesn't work since map returns a new array based on returned values in the callback. (If map works differently here there should be a link to that map).

can-define.types.set.html

• [ ] set( [newVal,] [resolve] ) is explicit that the behavior of setter depends on the number of arguments, just with an example showing a two functions with a different number arguments. It doesn't provide any information on how their different until Behavior depends on the number of arguments. heading later. This should probably just be a note with a link. Might want to split into 3 different signatures set(), set(newVal), set(newVal, resolve). Also, should we document set(newVal, resolve, lastValue)?
• [x] Use Lets see some common cases in first paragraph should be Let's.
• [x] Use should have codepen-able examples.
• [x] Use's second example doesn't have syntax highlighting.
• [x] Behavior subhead should have codepen-able examples and properly log.
• [x] Behavior subhead's third example mention that resolve will be called, but never calls resolve.
• [x] Side effects' second paragraph For example, in the example below is needlessly reiterative.
• [x] Side effects example should be codepen-able and log properly.
• [ ] Side effects might want to set console.log in getter to show that getter is being called when p.page is called.
• [ ] Merging the examples take a minute to catch up on. Can highlight the added if statement in the second example?
• [ ] Batched Changes while it's awesome to know that CanJS improves performance what does this mean to me as a user, should there be an example or does this really need to be a subheading?

can-define.types.type.html

• [x] Codepen-able run-able examples
• [x] Syntax highlighting
• [x] Use first bullet list should have links to DefineMap and DefineList
• [x] compute is undefined under Use Working with the 'compute' type. After some research it seems compute may be depreciated its documentation is under legacy. import { compute } from "//unpkg.com/can@5/legacy.js"; doesn't import stating Uncaught TypeError: Failed to resolve module specifier "can-compute". Relative references must start with either "/", "./", or "../".

can-define.types.typeConstructor.html

• [x] I think being declarative on the first paragraph of Type would be beneficial.

Type is called before type and before set. change to: The Type constructor is called before the type property...

• [x] For the sake of consistency propDefinition should either be linked in both {propDefinition} and [Type|propDefinition], or neither.
• [ ] PropDefinition should be camel case in {propDefinition}.
• [ ] Use jumps directly into code. There should probably be some text here, even if it's just elaborating the code below.
• [x] Use code example should be codepen-able and loggable.
• [ ] Use should either explain what the difference between from and to is in the example. I question the validity of this example, I can change the value to a number and no errors are thrown, maybe there needs to be an explanation of how this differs from a normal object.

can-define.types.value.html

• [x] value( prop )'s first example should be codepen-able
• [x] The Returns subheading under value( prop ) example should be codepen-able and loggable.
• [x] The second paragraph under Use starts with Lets instead of Let's.
• [x] The second paragraph under Use has the ubiquitous fullName property, which well being playful might subjective.
• [x] Both examples under Use should be codepen-able and loggable.

discussion:

I'm not sure if comparing value( prop ) methods to DefineMap methods is ultimately useful. Each article should be able to stand on its own.

Should each of the prop methods have their own section/signature (blue box) and sub bullet on value's table of contents?