Improve documentation (Tutorials, API documentation etc.)

[aashish24]

We have gallery which is great, but we are missing tutorials for example. @nicopresto @jbeezley @dcjohnston what you think?

[jbeezley]

There are two big things that should happen for documentation.

• Tutorials: I had started several jsbin examples (like this one) that were intended to fill that role. We should embed jsbin examples like this with some prose in the style of the romanesco examples in the RTD docs.
• API documentation: For this we need two things:
  1. Fill in missing/incomplete docstrings. I have been doing this as I go along. The new lines in my refactoring branch are probably half docstrings.
  2. Fix the jsdoc template to work better with our code structure. For example, show the classes with their namespaces geo.core.pointFeature rather than just pointFeature to distinguish the derived classes.

[aashish24]

Tutorials: I had started several jsbin examples (like this one) that were intended to fill that role. We should embed jsbin examples like this with some prose in the style of the romanesco examples in the RTD docs.

@jbeezley are you suggesting we create RTD manually (vs parsing the source code like we do right now?).

API documentation: For this we need two things:
Fill in missing/incomplete docstrings. I have been doing this as I go along. The new lines in my refactoring branch are probably half docstrings.
Fix the jsdoc template to work better with our code structure. For example, show the classes with their namespaces geo.core.pointFeature rather than just pointFeature to distinguish the derived classes.

I have slightly different view. Talking with some other folks including @danlamanna, I am thinking that we should follow D3 like API documentation which I don't think comes from the source code. Does it?

[jbeezley]

are you suggesting we create RTD manually (vs parsing the source code like we do right now?).

We do create RTD manually. Only the API docs come from the source.

I have slightly different view. Talking with some other folks including @danlamanna, I am thinking that we should follow D3 like API documentation which I don't think comes from the source code. Does it?

I don't like having the API documentation in a separate place. D3 doesn't use embedded docstrings. IMO, that makes the source code hard to read. Other popular libraries use jsdoc effectively. For example, glmatrix uses it with a very simple custom template, openlayers uses jsdoc with a highly customized template. I also recently found documentationjs which is compatible with jsdoc style docstrings. As it is, we have a hard enough time writing and keeping the embedded docstrings up to date. If we move them elsewhere, it will be orders of magnitude more difficult.

[aashish24]

We do create RTD manually. Only the API docs come from the source.

Ah, I see. I haven't looked at the doc. thanks for the update.

I don't like having the API documentation in a separate place. D3 doesn't use embedded docstrings. IMO, that makes the source code hard to read. Other popular libraries use jsdoc effectively. For example, glmatrix uses it with a very simple custom template, openlayers uses jsdoc with a highly customized template. I also recently found documentationjs which is compatible with jsdoc style docstrings. As it is, we have a hard enough time writing and keeping the embedded docstrings up to date. If we move them elsewhere, it will be orders of magnitude more difficult.

that's a good point. Can we not use these templates? @dcjohnston what you think?

[jbeezley]

We could base ours off of those templates, but my guess is that they are highly customized to the code they document.

[aashish24]

ah, I see. Worth investigating? In the mean time, I will add start adding some manual documentation (basic things) for RTD

[aashish24]

• API documentation - We have to document the API better (and add missing document for older code)
• Have JSDoc display the documentation better
• Add examples in RTD

[aashish24]

I think we are waiting for a example JS source file for improving the API documentation. @jbeezley any chance you can have one for us next week?

[jbeezley]

I'm working on integrating the template at https://github.com/davidshimjs/jaguarjs-jsdoc. This is the same template that openlayers uses and provides pretty good out of the box usability with minimal changes to our current docstrings.

[aashish24]

sounds great @jbeezley looking forward to it.

[jbeezley]

As mentioned in #697, here is a list of things we should check for in each file:

• Change each class definition to include an @alias tag (example).
• Tag events with the @event tag (example).
• Document events fired by functions (example).
• Add example blocks demonstrating how the function should be called (example).
• Where appropriate add @typedef tags (example). It might also be a good idea to move these all into a single file as well.
• Fix crosslinks so they work correctly (example).
• Use markdown syntax to display structured text (example).

I think it would also be nice to remove the immediately invoked functions since they are no longer necessary for commonjs modules.

[aashish24]

this is great @jbeezley. @jbeezley @manthey how should we split?

[manthey]

When documenting events, we end up with a title like geo.event.event:pan, which seems peculiar. Is there a way to have events look like geo.event.pan?

[manthey]

On our getter/setter routines where we return either the current value or the class instance, should the return type be {number|this} or {number|geo.map} (using an example where the value is a number and we are in the map class)?

[jbeezley]

Events names are usually just strings and don't typically have namespaces. For example, you would link to a change event as event:change. To avoid displaying them like this, we would have to modify the template used to render the documentation.

As far as getters/setters, I don't have a strong opinion. I guess {number|this} would be a more accurate representation of the behavior.

[manthey]

In the geojs examples, we refer to events via a namespace, e.g. geo.event.feature.mouseover and geo.event.mouseclick. Would it be better for the documentation to show them this way? Or resolve to the actual string, e.g. geo_feature_mouseover and geo_mouseclick?

[aashish24]

In the geojs examples, we refer to events via a namespace, e.g. geo.event.feature.mouseover and geo.event.mouseclick. Would it be better for the documentation to show them this way

My slight preference is for this (namespace) as I think that would be more useful for the developers but i am open on it.

[aashish24]

As far as getters/setters, I don't have a strong opinion. I guess {number|this} would be a more accurate representation of the behavior.

{number|this} sounds good to me as it is general as well.