Transcript from the "API Documenter" Lesson
[00:00:00]
>> Finally, last little step here, docs. So we have this thing, this other package that we installed called API Documenter. And what we're gonna do here is this, yarn API documenter input temp folder, output docs. Where to go. I forgot a little command there. It's API documenter markdown.
[00:00:28] So that's the command. I'm gonna run API documenter. I want it to generate mark down for me. There's another thing you could generate here, which I won't get into too much. Input is the temp folder, output is the docs folder, which by the way, it's gonna work really nicely with GitHub.
[00:00:49] So I now have a docs folder with all of this lovely markdown in it, including a little, this is a message saying this is a beta release. It's a preview, may change at any time. So let's commit this. And I'll show you what I mean by this playing very nice with GitHub.
[00:01:27] So I'm going to the place on GitHub where I've hosted this new repo. And we can see that 18 seconds ago I pushed a new commit. So this is pretty recent. Well first, before I go into settings here, let me show you what these docs look like just purely browsing them on GitHub.
[00:01:50] So here we go. This is where if we had multiple packages like if this were a mono repo, it's this little pitch for the monorepo course, you can see many different packages, each of their documentation show up here. And then you could drill into this and it'll show you the functions that are available with this nice little beta indication.
[00:02:09] And then if we look at average, Here's a description and there's the signature, here are the parameters, the return type. It's kind of basic, but it kind of comes for free. And mark down kind of works with a lot of different things with the nice little breadcrumb up here.
[00:02:28] So, here's what I find is a nice synergy. It used to be that GitHub Pages would. They had this gh pages branch, you'd have to commit your static site to your gh pages branch and it always felt weird to me to have a completely unrelated project. Your documentation, it's totally different than your source code, that's on your gh pages branch.
[00:02:59] It's not a different version of your source code. It's entirely different content. Now, I could say I want the source to be master and I can actually pick this docs folder and hit save. And I wonder if, we'll see if this actually works, but, Let's check it out.
[00:03:28] It's not there yet. I'll leave it as [LAUGH] an exercise for the reader to set up the Jekyll theme and all that. But the point is, once you have that theme set up, GitHub already understands markdown and can turn those into HTML. So this could be just an automatic self publishing thing.
[00:03:47] As soon as new content lands in that docs folder, GitHub Pages, it's Jekyll static site generation stuff, will kick into gear, make that HTML, you'll have that website published. You don't have to do a thing. Automatic publishing with each new commit that lands on master. So, with this included, we've got tests, linting, build, we can tell when our API surface changes.
[00:04:12] We can even validate that the API surface changes described in a pull request are the extent of the changes. Nobody forgot to update that report. Because we're testing that in CI and now we have API Docs on top of that. Really, really nice complete feature set. And I think we've ticked a lot of the most important boxes for a library that's authored in TypeScript.
[00:04:42]
>> Are there any other popular alternatives aside from our API documenter?
>> There are, you're talking about for API Docs Edwin, is that right?
>> Yeah.
>> So yeah, the question is, are there other alternatives for documenting APIs and this is a tricky subject because there are lots of options.
[00:05:07] But particularly for projects that might find themselves halfway between JavaScript and TypeScript, at least for a point in time. There are some solutions that work very nicely for just pure TypeScript and then some that work nicely for just JavaScript and they just fall apart when TypeScript gets involved.
[00:05:28] So those two exist. And then there's even another category like YUIDoc, where it doesn't even look at your code at all. YUIDoc simply reads comments. And that puts you in a situation where you have to do duplicate work. Every functions documentation must say, by the way, my functions name is this and the argument names that I receive are these.
[00:05:53] And keeping that in sync, it's just a huge pain. So, I've not found a great option that covers all of those bases. Things will either fall apart for modern JavaScript or TypeScript. Or they won't analyze the code at all. And it's all on you, as a developer to write your documentation.
[00:06:13] It's almost like they just strip away anything that's not a comment. That seems bad too. So I think that there's a lot of room for improvement in the space. If I had to pick one I probably would use ESDoc. But you wanna be careful because any TypeScript specific documentation tool like TSDoc, I think it is.
[00:06:40] Let me make sure that's what I think it is. Nope, sorry, it's type doc. This one here. So type doc is really interesting but, The way it's implemented is so tightly coupled with the compiler API, that it tends to lag way behind in terms of new compiler releases.
[00:07:02] So TypeScript 4.0 is out right now. It is entirely possible, I would not be shocked, if type doc reported nothing newer than 3.8. So it does put you in a position where you're always trying to catch up, catch up, catch up. And it feels silly to me to have a tool like this hold you back in terms of language level.
[00:07:25] So that's why I wouldn't necessarily go with this. ESDoc uses some of the same technology that ESLint uses in terms of building up that abstract syntax tree. And that is something that Microsoft and the TypeScript core team themselves, they help keep that up to date. And so it chases the new releases of the compiler a bit more tightly.
[00:07:52] And I think it's less risky to incorporate that. Now here's the good news though. Everyone's trying to align around JSDoc stuff. The whole point of this is the things that make for great tooltips in your own app. Everyone wants that same stuff to result in great documentation. So in some ways these tools can be dropped in like trade one the other.
[00:08:18] The API Docs will look different, but you won't have to go and retrofit a bunch of stuff to your own source code. And if you're interested in learning more, I'm very passionate about this space. So I have a little project here, On GitHub. It's called JS documentation cases.
[00:08:41] And what I have is a variety of different interesting projects like single file of JavaScript single file of TypeScript. A mix. Entry point that's JavaScript but it refers to some type script. So I have a bunch of these, seven different, actually, it's eight because I have a 3.1 here.
[00:09:03] So eight different types of projects times one, two, three, four, five, six, times eight different tools that can be used to generate documentation. And I keep a very close eye on which of these 64 combinations start to look okay. Mostly I want you to look at this and see Mike's done a lot of research in this area.
[00:09:25] And if there were something that was good and ready to use, he would probably just tell us to use that and I'm not saying that right now. I'm saying API extractor while it generates basic documentation, I trust it more than some of these other things. In no small part because Microsoft makes it and they use it for all of their own documentation.
[00:09:47] And for their own use of TypeScript, which they make themselves. So if this breaks, it will break for them and I trust that they will fix it. [LAUGH]