AST extracting the documentation for functions

[amlwwalker]

Hey, I came across Go-App and as a result this project. Really cool - been wanting something to learn about AST for ages. This is perfect.

My goal is to try and build some components using Go-App for generating web assembly apps and then use the functions and the comments to generate the documentation as part of the web assembly site - i.e the documentation auto generates with the webassembly app which would be pretty neat.

I was playing with your application and my first question (I'm very new to AST stuff) is:

If I enter

package main
// Nav
/*
 this function adds two strings together and returns the result
*/
func Nav(str1 string, str2 string) string {
  // add the two passed strings together
   res :=str1 + str2
  return res
}

into your application I get the comments block:

  Comments: []*ast.CommentGroup {
    &ast.CommentGroup {
      List: []*ast.Comment {
        &ast.Comment {
          Slash: 14,
          Text: "// Nav",
        },
        &ast.Comment {
          Slash: 21,
          Text: "/*\n this function adds two strings together and returns the result\n*/",
        },
      },
    },
  },

which is fine. However when I remove the comment within the function, i.e // add the two passed strings together I get an empty Comments group, i.e Comments: []*ast.CommentGroup {}, - I was wondering if this is a bug or something to do with how AST is generated? I.e oes the Comments: []*ast.CommentGroup {}, need a comment in the function to read the comments above the function.

My goal is to somehow (haven't got there yet) run the AST generator over a package, pull out all the comments and then the function and add those to a markdown file which will then be rendered by my webassembly application. I think using AST is a good way to do this (as further down the line I may want more granular control over how the markdown is generated.

Also - in this case, does the AST generated "know" that the comments before the function are "part" of, i.e related to the function specifcally? - Reason I ask is that if I make a second function with leading comments, all commentGroups seem to be at the bottom of the AST generated. Is there a way for it to know those comments are related to that function? Thanks

[lu4p]

Do you really want to learn how ast works? Otherwise you could just use https://pkg.go.dev/go/doc

Astextract is good for getting a rough ast representation useful for generating the same code independent from current position and documentation.

You don't want to generate new code using ast, but read in existing code and transform that into documentation.

This program isn't particularly good at that, you should most likely use https://pkg.go.dev/go/ast#Print instead as stated in the readme.