Documentation Issues

[justinbmeyer]

can-define

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

can-define.types.html

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

can-define.types.propDefinition.html

• @codepen examples
• 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
• 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. (
• codepen

can-define.types.defaultConstructor.html

• Use section should explain what it's doing
• 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.
• codepen examples
• complete review (I, justinbmeyer, has not completed it)

[indifferentghost]

can-define.types.identity.html

• 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

• 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.

• Use's first paragraph was probably meant to be a link. can-route.map -> can-route.data
• Use examples should be codepen-able and relavent examples.
• 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)?
• Use Lets see some common cases in first paragraph should be Let's.
• Use should have codepen-able examples.
• Use's second example doesn't have syntax highlighting.
• Behavior subhead should have codepen-able examples and properly log.
• Behavior subhead's third example mention that resolve will be called, but never calls resolve.
• Side effects' second paragraph For example, in the example below is needlessly reiterative.
• 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

• Codepen-able run-able examples
• Syntax highlighting
• Use first bullet list should have links to DefineMap and DefineList
• 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

• 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...

• 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.
• 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

• value( prop )'s first example should be codepen-able
• The Returns subheading under value( prop ) example should be codepen-able and loggable.
• The second paragraph under Use starts with Lets instead of Let's.
• The second paragraph under Use has the ubiquitous fullName property, which well being playful might subjective.
• 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?