chore/jsdoc-comments-for-createSite

[goblinfactory]

Add js docs comments on createSite Clarifying the code responsibility.

[nobkd]

Looks like a good description to me.

---

We will have to think how (, how much, and where) to use JSDoc in the project.
E.g. if we use the type multiple times, should we use @typedef or so? 🤷

(I'm not that proficient with JSDoc, so I searched how to do reusable types...)

Just some open questions...
(Results to those should also be added to the CONTRIBUTING.md)

[goblinfactory]

@nobkd it's a tricky question, because normally commenting is necessary for a published API.
Since users are consuming a framework, there's actually no "API" as such that needs documenting urgently. While there's only 3 or 4 core contributors we should delay making as many decisions as possible that allows us to collect more data and more a more informed decision later when specific pains are obvious and solution A or B is easier to choose from.

To be honest I was investigating a tricky refactor to inject settings from site.yaml, and was quite impacted with the lack of typings so any option that helps with this will be greatly appreciated. (so we might pull the discussion forward sooner than later.) Just my thoughts. I'll share the tricky branch a bit later tomorrow, since I think it's a good example of a small change in behavior impacting lots of files, and thus relevant to the typings/docs discussion.

[tipiirai]

If we take this route, I think we should use jsdoc comments consistently, and everywhere. Or what do you think? I'm personally more into skipping jsdocs and favor unit tests.

[goblinfactory]

@tipiirai I'm always in favor of tests that tell you how a system is supposed to behave. Especially if we want to support ongoing refactorings. I suggest we close this PR; we can always decide later we now want to start using jsdoc et al once the API has stabilised?

[goblinfactory]

@tipiirai perhaps just convert this to a dev comment.
Update ( a few minutes later) -> Argh... now I'm torn, that seems like waste. Can we please leave this as an open question for a bit? Now it doesnt feel right to NOT have this useful information here, and if we do have it it's wasteful not to simply expose it so that IDE's can show it as intellisense. I also agree that not being consistent is also wrong.

[tipiirai]

Cool. Closing this one. Thanks @goblinfactory !