Exploring TSDoc & TypeDoc | Typescript Documentation | Live Stream | Webdev

uh my main motivation for today's stream was because i've been thinking a lot about documentation and how to do it well and how to mostly do it automatically so that you know robots do it well for me and one of the big benefits of having switched typescript from javascript slash node is that a lot of documentation just sort of happens by virtue of writing code and that comes to types in particular in the shapes of apis what things return all that's good stuff uh but there are parts of documentation and parts of apis that need to be written for people you know written with pros and trying to figure out how to make that work is kind of what i've just been thinking about a lot uh and so i was digging into tools around that and the two things in particular that i wanted to dig into were a thing called ts dock and a thing called type dock which unfortunately sound like the same damn thing um so i just want to dig into those and try to use them on one of my projects and so that's what we're gonna that's what we're gonna do today so this project is a is available on node it's a it's a just a little repo that i made to sort of bundle up all of my convenience functions uh for typescript um and types and things that i was finding to be really useful across projects or things taken from bigger large libraries where i only wanted a function or two and so could just you know take that instead of reporting the whole library so it's sort of a nice little portable module um if we go to npm so we can get out to this package so this thing is called b scotch slash utility this is the documentation we're dealing with currently this is all manual asked documentation so this sucks every time i go add new stuff to it i have to go in and also add manual documentation the actual functions themselves are decently documented and so the trello i was having is there's an aspect of of discovery with an api so if somebody wants to use this or if i want to use this library and i import it how do i find the stuff that's in there that i can use um so with good intellisense with a tool like vs code in combination with typescript and all the right extensions then you can just sort of start using it and then hit things like if you're on windows uh was it alt space or things like that and get your list of autocompletes so then find the thing that feels that sounds like what you want right but when you're not familiar with a library or the general stuff that's in that api how do you find what you want so if you ever use a really large library like say the aws sdk or something in node you'll find that it is just impossible to find the thing you want because you can't guess at the name and so you can't even it's just really hard so i was trying to kind of help resolve that by just having the documentation available for all of the functions that are in this library but it's really annoying so i figured this was a good project since it does have documentation's attentive documentation for every function that's in here and it's very flat it's a it's a simple thing there are no classes it's a it's a very it's just functions all exported in a flat structure it should be very easy if anything would be easy to figure out how to apply an automated documentation where i can put docs alongside the actual code and have those all converted into a readme that looks something like this maybe not exactly like this but all the stuff is there and where i don't have to do all this extra work okay so here we go the things we're dealing with are a thing called ts doc so we'll start with that because it's kind of the root of it so i found this one looking for basically the js doc equivalent for typescript typescript is as you frequency described a superset of javascript that basically supplies static types uh what does that mean that means i'm going to declare that something is a string or a number or a string or a number or a particular weird object with a particular shape you know a set of key value pairs or whatever that i can do that and then because i have declared that then now my tools typescript linters other kinds of things know what it is that that thing is supposed to be so they can help me they can do autocompletes they can check for errors that i've made because i used a function that needs a string but the thing i passed to it is probably not a string that sort of thing so since typescript is a superset of javascript and javascript uses primarily a thing called jsdoc to to annotate it where jsdoc's main goal actually is to provide type annotations so so a lot of what typescript does by making a succinct programmatic way to define types sort of consumes most of the stuff that jsdoc is trying to do that said in a pinch you can just use js doc to get a lot of the typescript like functionality so if you're in just plain old javascript and you annotate it well with jsdoc um if you're in some sort of an editor that knows about typescript and is using it you actually basically get typescript features still so you can get a long way with plain javascript and js doc for entertaining your types and stuff um so with the change of typescript now the sudden we'd have to worry about all that type annotation so you can now use the remaining subset of jsdoc that's not about types the question is what does that even mean what what tools support it and the tools that are around for creating automatic documentation files and stuff uh are designed mostly around jstoc because that's what's been around for a long time um so that's also what i kind of been looking at and i didn't see anything that felt appropriate for typescript most things about jsdoc can't pull type data out of your typescript and so now you actually lose your type data in your documentation by using typescript and trying to annotate it with jstoc i figured there must be a way there is supposedly we'll find out which is ts dock exact same idea you can see it's a proposed standard it's backed by microsoft if i'm understanding all this correctly because this is you can see the package is maintained by microsoft which sounds good because so is typescript so is vs code all basically all the tools that i'm using here that most people are using when they're using typescript so seems like a good source and they go through they have so so they call these things tags we'll start we'll start using them you can see this in this context there's a particular syntax that indicates to uh your tools that a block of code is a a ts doc a typescript document documentation comment so it looks like this it's uh so if you're familiar with typescript and this is true also in several languages that the slash star and then star slash bracket multi-line comments for jsdoc and tia stock if you add that second star right there just right after that first one then your tools that understand jstoc or ts doc if you have tools to understand that then that is the indicator to them that whatever's happening now between that start and end for this comment is going to be uh ts docs or jstocks so then it can parse it and it can do stuff with it so you can see it's just a simple basic kind of ascii there's nothing interesting going on here but then there are these tags that sort of conceptually provide annotated information structural information and if you structure your stuff in the right way using these tags then jsdoc.tsdoc can pull that out and then your tools can use that so here you're seeing things like at params this is saying i'm describing a parameter and because they came in this order that i'm describing them the ones that should appear in that same order and in jsdoc you would put the type information here in ts doc the type information is already down here and so you only provide any other information you think is useful to add so so jsdoc again most of its tags have to do with annotating types with tia stock now it's all the rest of the stuff presumably plus some new things you can see everything that they have down here basically it's the kind of stuff you'd want to use to now describe things things that are now a little more human-friendly things that refer to one function or class to another uh things that tell us how we should treat a thing whether it's deprecated or do that duplicate it in here yes whether it's deprecated in this case it's just a remark so it must be some sort of an aside right and so by having these sort of standard ways of describing things then the tools can convert that into a standard format some sort of probably a json document or something and then additional tools can be used to convert that into an html document or markdown or whatever and so that's kind of the path we're trying to take is how do we annotate our stuff and then what tools can we use to take those annotations pull them out of the code and convert them into human friendly always up to date documentation there's just this general problem when it comes to your code that you write your code now you need tests for your code that's actually just another form of documentation that also repeats information about your code you also need to document the api for people so that they can read some human-friendly pros that describes how to think about it and use this thing but that again is just kind of the code all over again just in a different way and so you have all these different ways you need to represent what it is that you did but they are not functionally coupled to each other so if you change the code you don't have to also change the test hopefully the test fails as a consequence and so those are at least fairly coupled but if you change yeah it's basically making so you need things to change at the same time as the end goal and minimize how many things are just broken because they're not coupled and you can edit one the other one means the same thing or describes what it originally was and you don't have to edit that at the same time so that's ts doc that's kind of the overview again the idea here is that we're not going to be trying to take the ts doc standard go through a set of code start using that context and see if we can convert that into documentation that's now coupled and human friendly so if we look at the rest of the thing the documentation is pretty decent over here for tstock they basically point out that there are these other tools that have different interpretations of jstoc or whatever but the idea is that a whole bunch of things are making use of things like js doc and tstock and so if there's some standard that's very helpful and their goal here is to set the standard for tsdoc vs code um and typedoc are kind of the two tools we're really focusing on here but we also notice there's eslint um so i'm not actually sure what the tool set is for things that are going to help us with ts docker that's part we're trying to figure out here so we're kind of hoping here that between type doc and vs code and then eslint ts.plugin that will have everything we need to make all this work so this one is now type doc super confusingly named because the only reason the only way you could actually keep track of which one is which is if you already know about jsdoc so you can recognize tsdoc is basically you know parallel to that so that in contrast type doc must be the other thing typedoc is a thing that uses the documentation to create or sorry uses your ts dock comments to generate um documentation so that's what we're going to try to do all right so type doc as it says converts commas and typescript source code into html or json whatever so if it's json then we can do with it whatever we please if it's html we don't have to do with it whatever we please we can just type html which would be nice email is a cli or node module so if you're not that familiar with the node ecosystem this is super common uh npm packages make it very easy to supply a cli along with your community interface along with your code so if you're going to package your code and deploy it you can include some executables and then node the node ecosystem through npm handles all the process of making sure that thing ends up being executable even if somebody installs it on linux or windows or mac um so what you'll often see is that especially really popular tools have both cli components and also raw code components where you can now import the code and make your own pipelines where you're just your own tools built on top of the code itself instead of having to string together command line stuff through say bash scripts or something so supposedly all we have to do is this is just install it and then run it so i guess that's great that's easy enough presumably there are some details here about how to make it do a good job um but you know one step at a time right okay and finally we have eslint plugin ts doc so eslint if you're not familiar uh so if nothing with the concept of a linter but linting is the idea of sort of static checking meaning just looking at your code in essence of of code to discover things that are probably problems so it's different than like a compiler error or failing a test or whatever because they're a little more a little more functional so it's a little bit higher level trying to catch things before they hit those more downstream endpoints so so passing uh linter checks doesn't guarantee that you have good code it's it's looking for things so it's less checking the logic of the code than it is sort of the grammar and and that you've for simple things that would just be impossible to actually work for example cases where inside of your code it would have always returned in some place that downstream code could could never possibly execute for example so there are things like that that are detectable before you even compile it or um or run it so that's kind of what linters are for they can also be used for making your code look nice because you can set all kinds of rules like oh we have like you can call it an error if you're not using semicolons because javascript doesn't require semicolons or you call it an error if there aren't enough there's not enough indentation and then a linter for some of the rules can also auto fix things for you um i found recently that separating concerns of prettifying you know making the code look nice from looking for problems like things that'll break the code is really helpful and good practice so you can just write your code and then allow an automatic formatter to make it look nice so you just you just write hideous asked code and then run a thing that makes it look nice uh and then you can reserve the use of your linter for finding actual problems so eslint is the thing for basically javascript and typescript uh yes standing for ecmascript which is the sort of official real name of javascript so let's see what this thing is doing it's providing a rule for validating that typescript dot comments conform to the specification okay that's nice this basically will allow eslint to parse rts docs and then tell us if we're using them right yeah so i'm a tools first developer i always get my tool set up because uh prevents you from making mistakes and also helps you learn new stuff because the a really good tool provides hints prevents from doing bad things um uh provides easy way to do the right things so here's the project i already kind of went through the the npm page for this little bit so you saw the readme or at least the rendered version on npm so again the goal here is to take this thing and see if we can get most or all of it out of here and into the actual code or otherwise use the code itself as the documentation avoiding things that are pros that are not functional because those are the things that are that can mutate and then become wrong because they're not functional basically that question is how do we how do we convert our code into docs how do we just do that so here we go let's look at structure this project so we know what the dependencies are can get a sense of what's going on here we've got in the root read me file let's close the list we've got a readme file so we're looking at here we've got our ts config so this is the configuration that tells typescript how to interpret stuff how to compile stuff all that yes lint so this is now where i have my lynch rules so you can see basically all of my rules in here or almost all of them are now about typescript um the ones that remain are actually mostly ones i don't need anymore because i've added prettier but i had just added prettier and hadn't gone through the trouble of actually updating my uh eslint configuration file to get rid of the things i don't care about anymore so that's all that um so we'll do first now is install this new plug-in for eslint and then get our eslint rc updated to properly make it go where those new rules and the plugin that allows it to parse things properly is not going to apply to ts doc let's try to figure out how to install this stuff um so let's see if this is a well-written uh documentation um adding linter rules and and things like you know babel plugins like all this stuff is always more confusing than you think it will be because usually because you do it rarely enough that you it's not frequent enough for you to be like oh yeah i know exactly how this works so what does this thing say to do install that that's easy enough first things first let's install that okay i did it that was easy next thing is the config file add the eslint plug-in ts dock package to our plugins field right so that's all happening just in plugins that's all we got to do supposedly and then we're done so that's cool so the prettier docs recommend that you put stuff that isn't prettier before it the idea being i assume that prettier now cleans up all the other stuff that's happening behind it since it's purely decorative it doesn't actually functionally change things okay now supposedly our linter now has this plug-in all right so we've got our new insulin rule so supposedly that's done we can just sort of you know cross this off the list probably we would do it to enable the ts docs and text rule okay fine so it would be weird if this wasn't just on by default with the plugin but you know hey we'll do what they tell us avoid problems so we're going to add that so we've got this close that now we can install type dock so we just have that ready to go because we can just do a test run and just see what happens when we haven't even tried to do anything with it so for that we're going to do our little just a little another install so here's telling us to install it without that minus dash capital d or as you can see up here save dev that's the same as single dash capital d so they're having installed without that which means that this would be installed as a dependency so that even users of this module when they went to do an npm install at b scotch slash utility which is what this package publishes to they ended up installing type dock alongside it which is probably not what we want um so i'm gonna do uh minus d to make that go into dev config or dev whatever you call it dev dependencies and then yes dev dependencies and there it is perfect now that we have installed type dock it's now available locally and what npx will do is if we try to run it then it'll look for a thing called typedoc and our locally installed executables so that allowing us to just do npx type doc so what i like to do anytime i install a new cli is just run it with h just to see if it has a decent help and then if that doesn't work i'll try a dash dash help because everybody does it slightly differently and sometimes it's also just help without any dashes but you know just go down the list try the things this is nice it gives us basically all of these options it's hard to read in this context so hopefully their documentation their website is good so we get nice formatting and you know highlighting and stuff but it's nice to know that it's here it tells us how to use it gives us all the kinds of options for how it's going to work ooh it tells us what language is going to highlight i don't know why but i think it's actually because i believe you can document code because i think you can use markdown inside of ts doc and that will properly render so that means that inside that markdown inside that js dock you could have a code block and specify a language that isn't javascript or typescript and apparently that's fine and then it'll just syntax highlight anyway i don't know why you would do that but it's a thing that you could apparently do you can see it also comes with some themes so so again we can generate html with this so we could generate json with this if we generate html then we also could choose from different themes the themes are going to just apply different css uh presumably we could make our own theme if we wanted to but who has the time so we'll just pick one that looks good okay cool so now we've got everything installed we have seen that there's decent help so so we're ready to try this thing out so this whole quick start thing is something that i've seen in a lot of really good documentation and i've been trying to model which is given some project that you're hoping people will use you sort of basically say what is this for why is it useful is this thing to lease again quick start get people just in the door right so you don't talk about the options you don't talk about how it works you don't talk about the caveats you don't do any of that stuff you just say for most people most of the time if they do this tiny number of things they won't necessarily get the outcome they want but they'll get an outcome so now they've started they've got a sense of kind of how this thing works and then they also have a sense of what didn't work the way they wanted it to so as they start going looking through the configuration or sorry the documentation the deeper details of what the thing is that they're looking at and using now they know what questions to ask so here you can see how the code is organized the way that i like to organize things for typescript projects is to have a source folder where all my typescript stuff is because that way there's one compile step one set of configuration it's all very simple and then it all exports into one build folder that just mimics that same layout and so it it's understandable if it weirds you out that i've got like source and i've got my test stuff and my non-test stuff and the entry point is alongside like it's all a little weird but because of how publishing works with npm um i can just exclude the test code uh from the published package so that the structure remains the same just the tests aren't in there so this allows for a really simple structure it's easy for test code to access non-test code to test it it's easy to find the entry point everything's really easy to find and then because you can control how it gets published then it works out fine so here's our entry point you can see all this thing is doing like i said this is a simple project and it's just a flat export just everything is just exported just it's just all right there you can just grab all of it so this is the entry point and the question is if we just run ts no type dock on this what do we get let's find out mpx type dock one question is will it clobber my current readme who cares that's what it gets for okay npx type dock and then we'll point this to source slash index.ts that's pretty fast okay i'm gonna make another shell here just so that this stays up higher so it's easier to see just kind of ignore the stuff down here okay let's see what we got here so now you can see a bunch of stuff got exported but these are the things i changed so i'm gonna go ahead and just stage these to get them out of the way um so these are all the new things that have happened as a consequence of me running that command so let's see what these are so there's an index.html file that appeared um actually let's open this up here okay cool so this is also a folder called docs that feels like it makes sense if i combine that um so you can see it made an html file for for index so if you're unfamiliar with html the standard way of naming an entry point for for an html file is called index legacy reasons but the cool thing that lets you do on most web servers is you have a thing called index.html or php or whatever and then when you refer to a url that doesn't have.html um because it's like referring to a folder basically on the server's file system then if inside there there's a file called index.html that's what gets served um this isn't what has to happen that's just become a convention so it's kind of the default for a lot of things like apache and stuff and node sort of inherited that same idea for its module management system so this whole idea of like a file called index dot whatever the file type is is really common so here we've got this index file for this html so now here we go open with live server so this is a cool extension that creates a local server and then runs your html through it so that you don't have to do the whole like oh where where is my file so i can put file colon slash and then the full path to my file so my browser can show it nonsense uh you get to treat the website basically you're building um as a website so you just go to some local host address and so basically it just it creates a server on a port and just serves up your files from it okay so this is cool so this is what got generated without any options whatsoever so let's try to figure out what it did here um so you'll notice there's some fun stuff going on here uh this doesn't do anything to my code at least public hacks i'm gonna do classes there's no protective stuff going on here yet um though i still could probably mark different functions and stuff as public or private or whatever if i wanted to so that while they're technically not they wouldn't be documented which is a classic javascript trick because in javascript there's no search thing as private um everything is public and so there are tricks that and conventions that people use and then with jsdoc and presumably tstock you can use things like at private in your jstoc to indicate that something is not supposed to be exposed because again it just is because that's how javascript works um but by indicating that it's not then the tools don't expose it and so now even though it's technically available like somebody could use it they could get in there but they can't see that they can so it's not a security mechanism it's a mechanism to make sure that the api you intend to make it visible and available isn't one that people see okay so what does this thing do so it knew my title right and the only place that that thing shows up is in my package.json right that's the name which means that this thing reads the package.json so that's good to know it's pulling some information out of that uh what else we see so now this is just my readme file right so it looks like it makes the entry it makes the main page the thing you land on be the readme file so it's also great so that means that if i want to write a bunch of you know user facing pros so this kind of interest stuff like oh here's how you install it here's the quick launch whatever the stuff that isn't just the documentation for the code and how it works for the api but user-friendly tutorials and that kind of stuff um then i could still do that and i would still show up first which is great and you can see it has the list of exports um with the idea being because i gave it the entry point and so the entry point then can follow all of the code that ends up being eventually exported out of it and then reveal all of those things so like i said it's a flat project so there's a lot of stuff in here what is this thing it's an interface okay so i've got an export interface okay so it separately handles interfaces and types what do these icons mean so this is a t so it's a type so this is my any function type and then we've got this t with a zero in front of it don't know what that means no it's a type a right type of alias versus a type a list it's the same thing okay i don't know what that means okay if anybody can figure that out let me know i have no idea what the what is that zero doing and so now we know the default output looks again it must look at the package of json that's what it names this thing so that's cool it re it reads the readme and then basically dumps that thing into into here is the main view so what we saw in here for the output is the index.html then we have this modules file and so it looks like what happens here is that the is that the entry point for this we'll call it a website because it's got a couple pages but anyway um here it's probably take us back to home yeah so the home page is one index file that basically gives us our sidebar with all of our other modules and then this other html file appropriately called modules because they're called in uh in javascript so a standalone file that exports something and we can see here too that it also separately makes an interfaces folder uh interfaces are basically the shape of something like an object or whatever that is pseudo-interchangeable with the word type the concept of type in javascript we won't really get into that um but you can think of them as basically the same thing and then we are just other assets like the css images that it generates i guess and so so this is cool because if we wanted to we could then convert this into a website we can actually host it on github and so now all of a sudden as part of our automated pipeline of versioning this thing publishing it and so on we could have a website that is nicely hyperlinked and puts all the docs together so that's pretty cool i'm into it uh so now if we go back and look at this thing if you can look at this thing what do we got so now we have all of this stuff in here like i said we've got these types um we have these uh these looks like probably these are referring to functions i don't know what these icons mean i can't figure this out oh no oh yeah so these are objects right because i also because this whole thing exports flat i did add um oh this is horrible that's very hard to read but i did add uh here look at this in the code so you can see what i did here is i'm exporting all these different functions um this is not exported so i'm exporting these are functions and so these are making up those exported modules that are being displayed in the docs alongside that i'm also exporting from each of these files some of each of these library files that contain functions related to that sort of class of thing it's a loose hierarchy a object that has all that stuff the idea here being that if you wanted to import this thing directly um then you could get this or if you this this thing called array will basically be visible if you're using intellisense to figure out what's in here so if you were like oh i just want array functions you can basically import a thing called array which is just as object and now it's full of all the array functions so it's it's basically adding two ways that a person could access the functions that make up the library it's probably worth admitting that the only reason i'm doing this at all is for backwards compatibility because uh until i fully had made the switch from from javascript to typescript uh i had always been exporting things in this way and so now i'm just gonna have to keep doing it for this project which is you know slightly annoying but is what it is so that's what that is and it comes out as this just horrifying monstrosity of documentation uh this is cool though this links me to the co cool so this links me to in github for the same git commit it links me to the thing it's documenting so that is pretty cool i do wish this documentation wasn't so hideous because this is really hard to read huh i wonder if i could make that less hideous so far i don't know about this uh okay so the point here is that we've got some hideous documentation because it's basically just taking the raw uh information the raw uh like function declaration and stuff and then just just write it out no color highlighting nothing at least we got italics that's nice um such as really hard to read so having these docs isn't very helpful at least the name is separate so you can at least know what it is you're looking at so the question is is this thing classed in such a way that we can see its individual parts which would then mean how cool would bricks uh which because if it is then that means the css class can make it look nice signature symbol signature type okay yeah so it doesn't say what the type is but it tells us that it is a type which means this could be classed uh or could be styled via css to not look like crap so okay in principle we can make this look better so i guess that's good to know presumably someone's got some good themes out here we would just have to dig so similar time uh this is cool though this is basically just already kind of the thing that i wanted it to be right out of the gate without setting any options takes my readme gets my name and it gives me documentation for all my exported stuff so if i were to now provide additional documentation what's going to happen so here okay so this is interesting because now here this is technically a ts dock because it's a js dock and there's the same thing so this documentation here should somehow be appearing which one is this this is uh sort array sort numeric descending okay and that shows up here nice yeah look cool and then because i did because i did a code sample here so this is now markdown right and this is this section right here is a code block um and i've indicated that this is javascript because i could have said typescript but by saying it's javascript since people using this will also be using javascript that it is a little more everyone friendly but then it shows up in here and it's also nicely uh syntax highlighted okay so that's pretty cool uh so these are types what do these do okay these are tag references so if i were to slap like an alpha on that what does that mean what does that do i assume where does that go probably the bottom i don't know where would that go alpha okay so i can recompile this what if that's a watcher it's fine if it's a watcher probably doesn't type dock guides options watch it does have a watcher yes preserve watch output clears a screen between compilation steps so yeah let's not do that actually he cares i don't care what it's gonna do that's fine beautiful now change it just have it change live for us which is better all right so now that is rebuilt what do we get we get something that is upset okay so array truth compared to last that's what we're looking at sort numeric descending well that's not very interesting okay so it just sticks that on there uh i think you might also get let's see so if we indicate this is alpha we get hover text doesn't really do anything interesting for us either um because it's also deprecated let's see what that does so i got my watcher recompiled excellent this is a little little inconvenient i wish this was separate pages but we're going to do this eraser descending that's all that does okay does this annotate it in the it doesn't annotate it in classes anywhere either okay that was a nice actually that kind of sucks so so pain even overload only the first one shows the documentation so that's less than ideal okay good to know um what else we got what else do we have example experimental so it looks like these things just kind of show up as like little tags in this context back transition override remarks and see some remarks remarks okay main documentation for an api item brief summary followed by detailed remarks one or more detail pages show more okay so it's sort of like an aside i guess um private remarks oh cool interesting um throws type param virtuals private public private there's not that private it's kind of weird internal it's not planned to be used by third party developers okay and i think that's where some of these options come into play where there's uh like excluded terminal extra protected all that kind of stuff so that way you could say um again even though it's technically available i don't want that part of the api to be visible so that people don't use it and have things have bad things happen on accident um okay yeah so i feel like we already kind of hit the extent of what this is gonna do for us it's not a bad thing necessarily that means it's easy that means out of the gate it basically does what we want it to do um with some uh caveats and limitations um notably the main theme kind of blows it's really hard to tell what like this is this really needs some nice syntax highlighting it's way too hard to read so generics look bad that's one lesson um uh overrides i mean overloads don't document super well um it's not terrible but it's not super good um these linked to no it's just for this line so return it doesn't look that tight that type isn't exported so that's kind of a bummer okay yeah so anyway so there's some caveats here but it still seems like if i then so now if i went into my my readme and i took all of these all the documentation out of my readme which is basically like here's how to import this thing have some examples on how to use different ones and then move that into the just the functions themselves and now everything is inline it's all alongside the functions if i change or add a function just add stuff there and i'll just then appear where it needs to and then the readme file can be restricted to just being basically description of what this project is and uh some sort of a quick start process okay okay that's not bad it is okay i can get behind that um you could check out what it shows is markdown actually that's a fair point because it already is so this is fantasmic asks or says what does it do with markdown let's find out so let us first you see what happens without the plug-in um so now let's let's take one of these documents i have in here let's look at some of these string functions okay so let's look like these these fun template functions and then we can go into our strings library uh substitute library and then we can annotate these things so okay so this thing's already annotated so if we look at undent then that should just be the summary undent qr sdu on dent yep there's a summary great perfect so now if we take the all right right here so if we take this example here then this should then add some more markdown to it but this should render the way we want it to so now we have this annoyance but that is something we can deal with there we go okay but this is a code block so let's mark that off js these are comments that are supposed to show up inside the code block that off okay so that would be that's the idea like migrate the readme documentation into the actual uh code documentation so if we refresh that does it not exist anymore can i not go there uh-huh okay so that works properly um now what if we say what if we scream out the name of this thing undead and then let's like throw a let's throw a dang image in here huh let's put like oh crap what's the url just to some random image um let's see if i can remember these slash now dot net slash fit in slash 256 by 250. logos uh studio dot png is that one of them i feel like that's gonna be i think that's a real one actually let's check it in the check-in browser uh i have a um i have a uh what's right for that i have a thing set up on aws that we can host all of our images at their original resolution the original scale and then we can generate arbitrary urls to that same content and then the image of the specified size gets created on the fly and cached so then the next person who requests it gets an image of that same size that's now already been created so that way we minimize bandwidth um but that same thing can also be used too so this is the like the human readable version where you can kind of control its size and that's really it um but the the other thing that is it's actually using a thing called oh crap what is that uh oh node image processing cameras there's an s i think sharp that's the one uh so if you if you're into node um uh so so node doesn't quite have the extense extensive uh sort of file manipulation and like data manufacturing library stuff that like python has um not even close really but it does have some particularly good stuff and so one of those is image well i guess not a lot of image libraries but a few pretty good ones including sharp which is probably my favorite one that's very easy to use very human friendly their documentation is stellar um and uh it allows you basically to just take an image and then just you can chain commands to do stuff to it and spit out a new image so basically what is happening at aws is that it uses the source the raw original image and then just chains a bunch of things together and the cool thing is you can compose those in your url right so you basically can make a json document that describes like my resize parameters my uh i want to change it to grayscale i want to convert it to a jpeg um i want to crop it on a rotate like whatever any of those idiom manipulation that sharp can do you can just describe an adjacent document and then you basically base64 encode that use it as a url with some information about what image is referring to and stuff and then it does all that on the fly returns an image and then caches it so it caches it with that same url so the next person who asks for that same weird thing gets the same deal so i can show you that if we go to our website so if we look at the url this thing is requesting like look at this weird this weird url right it's like slash so those of you who do a lot of base64 and like data stuff like if you see ey capital j you're like i know i know what that is that's json because when you base 64 and code json the first character is always a left curly bracket the next character is always a double quote and so what you basically always end up with is a lowercase e lowercase y and a capital j because of that requirement not important but just kind of interesting anyway so you can see i got this long long thing if we took this if we took this and i went to like a base64 decoder and looked at what it was now where's my decoder decode i have to click it it's not just live see look at that it just describes what i want to look like boom now i got it so anyway that's pretty cool so that's how we handle dynamic resizing so that when you visit our website using some particular browser so if you're on a phone versus on a desktop or an ultra ride or whatever or safari which doesn't support certain certain file types although i think they recently just finally started supporting web p um there's a newer one that they also support now but you know this is the web dev game uh and so what that allows the website to do is to have all these fallbacks where it can request it can formulate a new url based on the size and pixel density of the browsers asking for it and also based on what file types it supports that way people get what they need at decent bandwidths which helps us and and they also get it in a way that is likely to look pretty good because it matches pixel density on their phone or desktop or whatever anyway so long story to say that url works so i never never make an image in html or markdown without alt text just don't do it against the rules uh b scotch studio logo even though we're just playing here so there's always two it's gonna have it okay so now we've got an image um so html is markdown so yeah let's just see what happens let's just see if we i guess depending on how sanitized it is i guess we'll find out uh so i'll put something in here like you know this is italics we'll just state effect um and then we'll say you know so is this um i could put some bold stuff in here supposedly put a list in here of some sort here's a list item and we will put a quote in here of some sort uh um put a quote here that says something like uh um type doc is great uh lincoln 2099 it's future ram lincoln okay so unfortunately we can't get any syntax highlighting here um mood watchers suggest trying uh actual script in here so if they're not sanitizing that out that would be hilarious but you know what let's try it why not well yeah we'll do an alert so it actually pops up that's fine uh there we go all right let's see what this does watching recompiling perfect um what do we got what do we got what are we out here let's close that close that close that reverse this oh my god it lets you do it we can just run javascript in here okay i mean that's not necessarily bad because the person controlling the javascript is the person running the docs so it's not necessarily a security issue um but it is hilarious okay so let's see what this looks like okay so why does it even say we would need a plug-in because it just it just uses it we're separated out of files yeah why do we even need that github wiki theme what is this is this if you wanted to like control how the markdown behaved or something oh i know it looks like it just already supports it oh that's cool so you could do really weird stuff with this interesting yeah yeah when moon watchers suggested putting that scrub tech in there i was like this isn't going to work but sure but you can just do it you know that means we could literally load like you could load like a v you could make like a single page app inside of this documentation you know like i could load view and then create a view object that does stuff right i mean i don't know why i would but i could do that well that is i'm gonna try it i'm gonna try it vjs uh views like like i mentioned earlier when you're setting up a thing even if you feel fairly familiar with it um if you very rarely actually do the setup phase then every time you do it you're just like you feel like an idiot because you don't know how to actually do it uh fortunately that probably could do it in a few little steps it's probably easy because i should be able to do it inside of without doing any installs so i should just be able to to use a script tag to load view this is another middle install so what i want to do i don't want it there we go cdn yeah so i should just be like to grab it let's get view three i oh now this is v2 docks view 3. so i just recently updated rumpus the rumbus website to use v3 so i'm still kind of figuring how to think about that what's taking you so long buddy there we go there we go okay view installation there we go so so i can just basically load view in here just load view and then so let's do that slap some view on here okay but i would need to be able to now put some sort of a container in here that i can stick something into uh okay so let's make a container we'll just call this i'll make a section that's a nice generic container um we'll give it an id we'll say this thing's id is what's called app that's kind of classic view slash react thing to do um that's it so now we got now we've got a mount point so that's great uh now i can make another script that actually so we're writing java writing javascript inside our markdown inside our typescript okay so i always i use the whole build process for this so i can't remember how to actually do without the build process but i should be able to plug a thing in there just like inject it if you create app yeah there we go because i just make a template i can shove it in there i can tell where i want it to go just record a compiler this does not kind of render a thing return view right because if it's a template you have to do the compiling step okay can i do this can i figure out how to do this i'm going to do it so do template syntax inside of forex it's not going to be compiling though i've never used v without the compile step can i just do it here here we go actually let's look at uh codepen codepen codepen so we look at codepen and then we make a we make a viewpin how do they do it we just look what they did oh no they still do a single oh crap okay that's still compiled okay so that didn't do it i know you can do without compiling how do you do it single file components testing is going up routing basics hmm how do i do it a few three three three fe3 uh render template compile how do we do it render functions template compilation without webpack so here we go maybe no it's still doing okay sorry it's just looking at this javascript which is also overdue so that's fine so right then we use a module syntax for that to work so then it imports app that's if we have that there okay crap all right i don't know enough about using view without a compile step to do this in an effective way so that's a bummer just burn in time um but we probably could though you know probably could go to the intro page somebody says was it in there somewhere is there something about vgs vgs intro page does it show me is it is that all i have to do that can't be right can it is that right because that sounds absurd right because then this thing should expose a global called view if this works and then so that gets loaded which allows this thing to go if this is all behaving and assuming the synchronicity stuff behaves the way we would think it's looking for an element with an id of app that exists supposedly um and then it's injecting some data called message into it which i'm not actually using wait can i just like can i just put a template syntax in here can i just do that because that's what it looks like for compiled stuff is the same is it the same okay on dent where's that here there it is okay yeah that makes sense as in didn't work livebody app right because i still because it's creating a new view instance and then it's supposed to insert in there now is this just a synchronicity issue so for the console here what do we see view is not a constructor yeah it's not available but it says it's supposed to be there it's just because we need to import view beside all it is yeah clearly the fact that i never do just raw coding for websites means i don't know anything import view from view because this is now assuming that this thing is going to pass us now we have to take this type module is that how you do it does anybody know how any of this works i have no idea well he says it's also about view dot h uh uh uh this is not for ludum dare this is just me dude i'm the web developer for peace gotcha i'm just doing weird stuff um seth i believe is going to be doing a ludum dare stream i think that's next week two weekends two weekends um saturday so 13th yeah it's like it's two weekends um so he claimed that he was going to and i think he would said it on the podcast so if that's the case then i think he has to hold himself to it you know um if he didn't say that out loud to people besides us then uh whoops i guess april 23rd yeah so two weeks yup yup yup yup yup um all right this view stuff is something i'll just play with at a later date because it's already passed by attended end time for this thing so anyway thanks for watching um i hope this was interesting useful and or entertaining to some extent there's some pretty uh you know nerdy stuff uh i i appreciate everyone who's willing to spend an evening with me watching me learn about documentation of typescript that is uh that's pretty specific um uh so yeah i would uh love for you to share with me any cool documentation tricks you come up with especially if it's typescript in javascript since that's you know where i'm doing stuff um so uh we've got our discord for the studio which is a discord dot gg slash b scotch so you can come in say hi tell me stuff you can tweet at me at cost or ad i think there's a link somewhere in this thing i don't know somewhere somewhere on twitch there's a link for that um and yeah if you've if you've learned any things or want to show me that you figured out how to get view working inside the comments of ts doc uh that'd be cool i'd be into that um yeah so thanks for thanks for coming by um uh omnicarr welcome came at 6 30 pst instead of cst yep that's bad timing that's uh that's now so right isn't that now yes because you're two hours behind yeah so whoops i know i definitely put cst though in everywhere i put it so i can't take any blame for that um yeah reblog thanks for coming uh smallgram ask doing your stream on the commercial changelog tool um yeah actually i would like to i haven't actually done anything with it since that stream um so i still want to do that that is the tool that i want to make before i did it though because i had this question of um can i can i improve the documentation process so that it's just simpler because if i already knew that ahead of time then i could just take advantage of that with that project so that was that was a lot of why i was doing this for this one um uh able will tipple wick which sounds uh it's just a lot like a rumpus username but maybe maybe it's not some other source uh was adequately whelmed that's exactly what i'm going for you know don't want to hit under don't want to head over it's too much just uh do we want to avoid those extremes and go go right for the wilm um what else we got here might have been some other stuff take a quick check yeah that looks like that kind of sums it up mood watcher said suggested try logging a view on the console good idea yeah i should do some console exploration and see where does view show up when you just load it um but there's also when it comes to html loading scripts by default they don't load as modules they load basically in global scope but it's possible that the view whatever whatever it is is coming from the cdn it's possible that that thing is a module and so in order to access it i would need to identify it as a module and then also use import syntax and the part that i don't know it's going to require some playing to figure that out yeah anyway thanks for coming everybody i'm gonna shut this thing down and uh uh hopefully i see you again again say hi hit say hi on twitter say hi discord whatever it is that you feel like saying hi if you're into this kind of nerd stuff there's i think you can get alerts when the stream goes live and again seth will be streaming also in a couple weekends um doing game maker stuff doing game dev i also have a newsletter that i've been doing that's also just weird nerdy stuff a lot of typescript a lot of web dev so if you're into that kind of thing you can go to tinybs.com devchat tidybs.com is a url shortener i made that just links to all of our stuff so you know that's fun that could be another thing we could do at some point talk about how does that work uh that's it so smargam says love the newsletter appreciate that i'm glad you're enjoying it i've been having a lot of fun writing it um yeah everybody just have a great evening and uh get some sleep probably depending on your time zone yeah right bye everyone so here okay so this is interesting because now here this is technically a ts dock because it's a js dock and there's the same thing so this documentation here should somehow be appearing which one is this this is uh sort erase sort numeric descending okay and that shows up here nice yeah look cool and then because i did because i did a code sample here so this is now markdown right and this is this section right here is a code block um and i've indicated that this is javascript because i could have said typescript but by saying it's javascript since people using this will also be using javascript that it is a little more everyone friendly but then it shows up in here and it's also nicely uh syntax highlight so if i were to slap like an alpha on that what does that mean what does that do i assume where does that go probably the bottom i don't know where would that go alpha okay so i can recompile this what if that's a watcher it's fine if it's a watcher options watch it does have a watcher yes preserve watch output clears a screen between compilation steps oh yeah let's not do that actually he cares i don't care what it's going to do that's fine beautiful now i could change it just have it change live for us which is better now that is rebuilt what do we get we get something that is upset sort numeric descending well that's not very interesting okay so it just sticks that on there because there's also deprecated see what that does so i got my watcher all that does okay does this annotate it in the it doesn't annotate it in classes anywhere either so so pan even overload only the first one shows the documentation so that's less than ideal okay good to know um almost forgot what else do we have example experimental so it looks like these things just kind of show up as like little tags in this context background override remarks remarks okay main documentation for an api item brief summary followed by detailed remarks so it's sort of like an aside i guess internal it's not planned to be used by third party developers okay and i think that's where some of these options come into play where there's uh like excluded terminal extra protected all that kind of stuff so that we could say again even though it's technically available i don't want that part of the api to be visible so that people don't use it so i feel like we already kind of hit the extent of what this is going to do for us which isn't a bad thing necessarily that means it's easy that means out of the gate it basically does what we want it to do um with some uh caveats and limitations um notably the main theme kind of blows it's really hard to tell what like this is this really needs some nice syntax highlighting it's way too hard to read so generics look bad that's one lesson um uh overrides i mean overloads don't document super well so return it doesn't look that type that type isn't exported so that's kind of a bummer so now if i went into my my readme and i took all of these all the documentation out of my readme which is basically like here's how to import this thing have some examples on how to use different ones and then move that into the just the functions themselves and now everything is inline it's all alongside the functions if i change or add a function just add stuff there and it'll just then appear where it needs to and then the readme file can be restricted to just being basically a description of what this project is you could check out what it shows is markdown actually it's a fair point because it already is so this is fantasmic asks or says what does it do with markdown let's find out so let us first see what happens without the plug-in um so now let's let's take one of these documents i have in here uh let's look at some of these string functions okay so let's look at like these these fun template functions and then we can go into our strings library subset library and then we can annotate these things so okay so this thing's already annotated so if we look at undent then that should just be the summary undent qr sdu on dent there's a summary great perfect if we take this example here then this should then we can add some more markdown to it but this should render the way we wanted to so now we have this annoyance but that is something we can deal with yeah but this is a code block so let's mark that off okay so that would be that's the idea like migrate the readme documentation into the actual uh code documentation uh-huh okay so that works properly um now what if we say what if we scream out the name of this thing undead and then let's like throw a let's throw a dang image in here six logos studio dot png never make an image in html or markdown without alt text just don't do it it's against the rules uh b scotch studio logo even though we're just playing here so there's always two it's a good habit uh so html is markdown so yeah let's just see what happens let's just see if we i guess depending on how sanitized it is i guess we'll find out uh so i'll put something in here like you know this is italics we'll just state effect um and then we'll say you know so is this um i could put some bold stuff in here but this is bold supposedly put a list in here of some sort here's the list item and we will put a quote in here of some sort type doc is great uh lincoln 2099. it's future abraham lincoln okay so unfortunately we can't get any syntax highlighting here um uh mood watchers suggest trying uh actual script in here so if they're not sanitizing that out that would be hilarious but let's try it why not i will yeah we'll do an alert so it actually pops up that's fine uh [Music] all right let's see what this does watching recompiling perfect um what do we got oh my god it lets you do it we can just run javascript in here okay i mean that's not necessarily bad because the person controlling the javascript is the person running the docs so it's not necessarily a security issue um but it is hilarious okay so let's see what this looks like okay so why does it even say we would need a plugin because it just it just uses it yeah why do we even need that so you could do really weird stuff with this you know that means we could literally load like you could load like a v you could make a like a single page app inside of this documentation you know like i could load view and then create a view object that does stuff all right this view stuff is something i'll just play with at a later date anyway thanks for watching um i hope this was interesting useful and or entertaining to some extent there's some pretty uh you know nerdy stuff uh i i appreciate everyone who's willing to spend an evening with me watching me learn about documentation of typescript that is uh that's pretty specific so yeah i would uh love for you to share with me any cool documentation tricks come up with especially if it's typescript in javascript since that's you know where i'm doing stuff um so uh we've got our discord for the studio which is a discord dot gg slash b scotch so you can come in say hi tell me stuff you can tweet at me at cost or ad i think there's a link somewhere in this thing i don't know somewhere somewhere on twitch there's a link for that um and yeah if you've if you've learned any things or want to show me that you figured out how to get view working inside the comments of ts doc uh that'd be cool i'd be into that yeah anyway thanks for coming everybody i'm going to shut this thing down and i hope that i see you again again say hi hit to say hi on twitter say hi discord whatever it is that you feel like saying hi if you're into this kind of nerd stuff um there's uh i think you can get alerts when the stream goes live and again seth will be streaming also in a couple weekends um doing game maker stuff doing game dev uh i also have a newsletter that i've been doing that's also just weird nerdy stuff um a lot of typescript a lot of web dev so if you're into that kind of thing you can go to tinybs.com devchat tidybs.com is a url shortener i made that just links to all of our stuff so you know that's fun that could be anything we could do at some point talk about how does that work that's it so smargam says love the newsletter appreciate that i'm glad you're enjoying it i've been having a lot of fun writing it um yeah everybody just have a great evening and get some sleep probably to putting on your time zone

Channel: Butterscotch Shenanigans

Views: 3,539

Keywords: webdev, web development, typescript, node, node.js, nodejs, docs, documentation, tsdoc, tsdocs, jsdoc, jsdocs, typedoc, typedocs

Id: La56RcRrPIo

Length: 78min 41sec (4721 seconds)

Published: Fri Apr 23 2021