Better documentation and contribution guide

[le0tan]

Is your request related to a problem?

Currently not all functions in MarkBind are well-documented, and in the devguide there's no overview of how the generation works - which may make it difficulty for a newcomer to get started with contributing to MarkBind.

Describe the solution you'd like

• JSDoc for all functions
• Introduction to the architecture of MarkBind
• Contribution guide to components (adding new components or adding features to existing components)

Describe alternatives you've considered

na

Additional context

na

[nbriannl]

I agree, it would be really good to end off the semester with good documentation for future MarkBind devs.

[nbriannl]

Related to #816 #1139

[jovyntls]

• JSDoc for all functions

Could I check what the scope of this would be (do we want all functions to have JSDoc)?
Some cases to consider:

• for groups of functions (such as processXXXAttributes) that perform a similar job - may be better to have one overarching JSDoc comment for the group since a JSDoc for each function may be repetitive and not provide additional value to the reader
• simpler functions that might be self-explanatory, e.g. isMarkdownFileExt, might not need JSDocs?

[tlylt]

• JSDoc for all functions

Could I check what the scope of this would be (do we want all functions to have JSDoc)? Some cases to consider:

I feel that this scope is too broad and perhaps a little impractical.

Also given that we are moving to TypeScript in the future, JSDocs could be less useful in general (the input, output return type part).

[kaixin-hc]

I think the most confusing part of the js section is the Site Generation file, and the confusion mainly comes from how large it is rather than the functions being undocumented. Perhaps if #1756 can be achieved we can close this issue?

[ang-zeyu]

@jovyntls @tlylt agreed. Jsdocs could still be useful for providing high level descriptions of classes / functions.

To provide some context, at this point #1039 we haven't really been considering typescript yet (was suggested in the thread briefly).

I would this guess this was just a really "easy" alternative we went for (but turned out difficult to statically enforce).

We can cleanup the extraneous jsdocs while doing typescript conversion as well.

Perhaps if #1756 can be achieved we can close this issue?

👍