Adopting a standard way to document Frontity APIs

[luisherranz]

I think it’s time we adopt a standard way to document our APIs in the documentation because so far we’ve done it without too much rigor and it’s a bit of a mess.

I’m inclined to TSDoc from Microsoft because it’s the standard of TypeScript and all our APIs are written in TypeScript. It also has the benefit of having built-in support for VSCode, so the APIs we do in TSDocs also appear when people code in VSCode. It also supports markdown, which is cool.

microsoft/tsdoc

I have no idea how to move/copy from TSDoc to our docs. Maybe we can generate some API-only docs automatically in each PR and copy and paste the relevant parts when writing the real docs. Something like TypeDoc could help.

I’m certainly not an expert on this so any feedback or other ideas are more than welcomed.

cc: @documentation-team @dev-team @SantosGuillamot

[juanma]

Yes, I like a lot the idea.

@luisherranz

Maybe we can generate some API-only docs automatically in each PR and copy and paste the relevant parts when writing the real docs. Something like TypeDoc could help.

Something like this would work. But we should find the right format to show in the gitboook docs. I like this reference → https://www.gatsbyjs.org/docs/browser-apis/#disableCorePrefetching

This is, showing for each method or property the final user can use for their projects…

For properties

• type
• name
• description

For methods

• type
• name
• description
• arguments
  • name
  • type
  • description
• returns
  • type
  • description

For both

I would add examples of using these methods/properties.
I wouldn’t include the original typescript code in the docs but a link to the github repo part where this method/property is defined

[SantosGuillamot]

I agree it’s pretty important to start standardizing our APIs I’ve taken a quick look at TSDoc and, apart from being the standard, it looks easy and great. We can give it a try.

[luisherranz]

Do we all agree on start using TSDoc in our code now?

(and we’ll figure out later how to export that to copy and paste to the documentation)

• Yes, let’s use TSDoc.
• No, let’s discuss more options.

[juanma]

@luisherranz

and we’ll figure out later how to export that to copy and paste to the documentation)

Maybe this plugin can help for this

typedoc-plugin-markdown

[luisherranz]

Yep, I was just trying it out

I have created a new branch with a test of the @frontity/error package:

• Branch: https://github.com/frontity/frontity/tree/tsdoc-test
• This is how the comments looks like in the code: https://github.com/frontity/frontity/blob/tsdoc-test/packages/error/src/index.ts
• This is the markdown it generates: https://github.com/frontity/frontity/blob/tsdoc-test/tsdoc/error/modules/_index_.md

Let me know what you think.

[juanma]

I think that having this kind of detailed API documentation is a good thing for both:

• internal team
• contributors

Maybe this format is too detailed for docs.frontity.org but we can think on a better format for this site based on this output

Perhaps it has sense having the complete API documentation available in a site apart (I’m still not sure about this)

[mmczaplinski]

TSDoc looks great. I especially like that it autogenerates the links to the source file like:

I’ve seen this in the lodash docs and Gatsby also has the same feature. I think it’s very helpful and I feel like it encourages people to read the source when in doubt

1. I guess we still need to see how gitbook formats the markdown that is generated by typedoc to make sure that it doesnt mess it up.

2. I don’t think that the information is “too detailed”, but the problem is more that it’s not very readable with the default styling that github applies to the markdown. Can we add custom CSS to gitbook? E.g. gatsby docs have all the same info but styled in a much more readable way

[David]

I was playing with TSDoc and Typedoc while writing docs for the useConnect hook and I found some problems.

The code is in the use-connect-tsdoc branch.

1. When you re-export code with re-defined types (like in the case of connect) you would have to write the documentation spreaded on several files. For example, if you want the docs to be shown when you place the mouse over connect, in the import sentence, that documentation must be written in packages/frontity/src/index.ts#L15-L26.
   
   
   
   
   
   But if you place the mouse over connect where it’s being used, the documentation comes from a different file: packages/types/src/connect.ts#L14-L27.
   
   
   
   
   
   For both cases, if you don’t write the documentation in those places nothing will appear.

---

2. I haven’t managed to generate the documentation for the Frontity package well. Some properties that are directly exported from other packages (like useConnect from the connect package) are empty, even though VSCode shows the correct documentation (written in packages/connect/src/index.d.ts#L126-L135.
   
   
   
   
   
   This is the generated documentation for useConnect in the Frontity package documentation compared to the generated for connect.

[luisherranz]

@David I’ve also found some inconsistencies on how VS Code handles TSDocs but in my opinion, that’s not something we should be worrying about. Of course if we find that documenting things in some particular way makes improves this, then we can start doing so.

But for me, this is a VS Code problem, not ours. So I won’t worry too much. If our code is properly commented using TSDocs and they improve the way they show them, it should appear.

[luisherranz]

I have started a new PR that adds a command typedoc to generate the markdown files in our frontity/frontity repository: https://github.com/frontity/frontity/pull/455

Unfortunately, I found the following problems:

• It doesn’t work with nested properties.
• There is no way to mark what is public and what is not.
• Each time it builds, it changes all the files, because it’s adding the current commit hash in all the links. That makes it unusable for PRs, because it will show unrelated changes for +50 files and it makes really hard to see what file contains not only changes to the links but other changes.

I’m going to stop trying to make Typedocs work for our code. I don’t see it viable right now.

Automating the generation of markdown from our TSDocs is still a nice goal, so in the future we can:

• Revisit the Typedocs projects to see if the current issues are solved.
• Try other TSDocs-to-markdown tools.
• Develop an ad-hoc tool for our use case.

---

@documentation-team, maybe until we solve that you can come up with a markdown template that we can use across all the documentation to standardize the APIs? Something that is easy to use to move from TSDocs to markdown, even if it has to be manually copied and pasted. What do you think?

[luisherranz]

Closed in favor of Code <-> Documentation workflow.