authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-20 19:17:00+02:00
committergravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-20 19:17:00+02:00
logc481510c99ab29903350a834810bdcac32dbd9ea
tree93d30e203b38f33ea297f9ad46170226c2a40ebb
parenta63a1c5cb9fd31a57e8371e6cba5f316bd3f2a65

autodoc: show more doc comments for namespaces and types

previously, in the container view (the type of view that you see when you look at `std` for example), when listing types and namespaces, we would only show doc comments places on the direct child decl, which in the case of the `std` namespace, for example, it's just a bunch of re-exports. now, if we don't find a direct doc comment, we chase indirection and display doc comments placed directly on the definition, if any. this is the precise priority order: ``` /// 1 pub const Foo = _Foo; /// 2 const _Foo = struct { //! 3 }; ``` The numbers show the priority order for autodoc.

1 files changed, 44 insertions(+), 8 deletions(-)

lib/docs/main.js+44-8
...@@ -3053,8 +3053,21 @@ Happy writing!...@@ -3053,8 +3053,21 @@ Happy writing!
3053 if (typeIsErrSet(declValue.expr.type)) {3053 if (typeIsErrSet(declValue.expr.type)) {
3054 errSetsList.push(decl);3054 errSetsList.push(decl);
3055 } else if (typeIsStructWithNoFields(declValue.expr.type)) {3055 } else if (typeIsStructWithNoFields(declValue.expr.type)) {
3056 if (getAstNode(decl.src).docs) {3056
3057 namespacesWithDocsList.push(decl);3057 let docs = getAstNode(decl.src).docs;
3058 if (!docs) {
3059 // If this is a re-export, try to fetch docs from the actual definition
3060 const { value, seenDecls } = resolveValue(decl.value, true);
3061 if (seenDecls.length > 0) {
3062 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3063 docs = getAstNode(definitionDecl.src).docs;
3064 } else {
3065 docs = getAstNode(getType(value.expr.type).src).docs;
3066 }
3067 }
3068
3069 if (docs) {
3070 namespacesWithDocsList.push({decl, docs});
3058 } else {3071 } else {
3059 namespacesNoDocsList.push(decl);3072 namespacesNoDocsList.push(decl);
3060 }3073 }
...@@ -3068,8 +3081,19 @@ Happy writing!...@@ -3068,8 +3081,19 @@ Happy writing!
3068 if (typeIsErrSet(declValue.expr.type)) {3081 if (typeIsErrSet(declValue.expr.type)) {
3069 errSetsList.push(decl);3082 errSetsList.push(decl);
3070 } else if (typeIsStructWithNoFields(declValue.expr.type)) {3083 } else if (typeIsStructWithNoFields(declValue.expr.type)) {
3071 if (getAstNode(decl.src).docs) {3084 let docs = getAstNode(decl.src).docs;
3072 namespacesWithDocsList.push(decl);3085 if (!docs) {
3086 // If this is a re-export, try to fetch docs from the actual definition
3087 const { value, seenDecls } = resolveValue(decl.value, true);
3088 if (seenDecls.length > 0) {
3089 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3090 docs = getAstNode(definitionDecl.src).docs;
3091 } else {
3092 docs = getAstNode(getType(value.expr.type).src).docs;
3093 }
3094 }
3095 if (docs) {
3096 namespacesWithDocsList.push({decl, docs});
3073 } else {3097 } else {
3074 namespacesNoDocsList.push(decl);3098 namespacesNoDocsList.push(decl);
3075 }3099 }
...@@ -3215,8 +3239,19 @@ Happy writing!...@@ -3215,8 +3239,19 @@ Happy writing!
3215 3239
3216 let descDom = liDom.children[1];3240 let descDom = liDom.children[1];
3217 let docs = getAstNode(decl.src).docs;3241 let docs = getAstNode(decl.src).docs;
3242 if (!docs) {
3243 // If this is a re-export, try to fetch docs from the actual definition
3244 const { value, seenDecls } = resolveValue(decl.value, true);
3245 if (seenDecls.length > 0) {
3246 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3247 docs = getAstNode(definitionDecl.src).docs;
3248 } else {
3249 docs = getAstNode(getType(value.expr.type).src).docs;
3250 }
3251 }
3252
3218 if (docs) {3253 if (docs) {
3219 descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));3254 descDom.innerHTML = markdown(shortDesc(docs));
3220 } else {3255 } else {
3221 descDom.innerHTML = "<p class='understated'><i>No documentation provided.</i></p>";3256 descDom.innerHTML = "<p class='understated'><i>No documentation provided.</i></p>";
3222 }3257 }
...@@ -3241,16 +3276,17 @@ Happy writing!...@@ -3241,16 +3276,17 @@ Happy writing!
3241 for (let i = 0; i < namespacesWithDocsList.length; i += 1) {3276 for (let i = 0; i < namespacesWithDocsList.length; i += 1) {
3242 let liDom = activeList.children[i - offset];3277 let liDom = activeList.children[i - offset];
3243 let aDom = liDom.children[0];3278 let aDom = liDom.children[0];
3244 let decl = namespacesWithDocsList[i];3279 let { decl, docs } = namespacesWithDocsList[i];
3245 aDom.textContent = decl.name;3280 aDom.textContent = decl.name;
3246 aDom.setAttribute("href", navLinkDecl(decl.name));3281 aDom.setAttribute("href", navLinkDecl(decl.name));
3282
3247 3283
3248 let descDom = liDom.children[1];3284 let descDom = liDom.children[1];
3249 descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));3285 descDom.innerHTML = markdown(shortDesc(docs));
3250 if (i == splitPoint - 1) {3286 if (i == splitPoint - 1) {
3251 activeList = domListNamespacesRight;3287 activeList = domListNamespacesRight;
3252 offset = splitPoint;3288 offset = splitPoint;
3253 }3289 }
3254 }3290 }
32553291
3256 domListNamespacesLeft.classList.remove("hidden");3292 domListNamespacesLeft.classList.remove("hidden");