Question: Support for kdoc

mediavrog commented 4 years ago

So in the examples and the test cases, it seemed that single line comments are stripped from the AST output. Now I could not find a reference or test case for class or function documentation (kdoc). Will this library parse them into some nodes or will comments be ignored in the output?

drieks commented 4 years ago

Hi @mediavrog,

all comment are part of the raw ast, but they are currently not attached to a class.

I added an example here: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.kt.txt

As you can see in the raw ast, the KDoc comment is attached to the package header: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.raw.txt#L13

I already added a class named KlassComment to represent comments in the summary ast: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.summary.txt#L1

But nested (in the ast) comments are not yet visible.

takanuva15 commented 3 years ago

I am interested in this feature as well; I want to parse just individual kdoc comments and verify their contents as part of my workflow.

@drieks Can you recommend me which classes within this ast library I should look at for making such a feature possible? (ie a kdoc comment declared above a class will be associated with that KlassDeclaration, and the kdoc's contents will be recorded too).

kevinvandenbreemen commented 3 years ago

Hi @mediavrog,

all comment are part of the raw ast, but they are currently not attached to a class.

I added an example here: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.kt.txt

As you can see in the raw ast, the KDoc comment is attached to the package header: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.raw.txt#L13

I already added a class named KlassComment to represent comments in the summary ast: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/Issue17.summary.txt#L1

But nested (in the ast) comments are not yet visible.

Hey there, I too am interested in being able to parse kdoc. However I've checked the links posted above and they are going to page not found errors. Do you have any other examples?

At the moment I have been able to locate comments using the "attachments" field on AstWithAttachments. Without side-tracking the conversation and intent of this particular question too much I am wondering: what is the purpose of an AstWithAttachments? What are attachments and what makes them different from an Ast node's children?

Thank you kindly, Kevin

drieks commented 3 years ago

Hi Kevin @kevinvandenbreemen,

you can find many examples in the unittest folder: https://github.com/kotlinx/ast/blob/master/grammar-kotlin-parser-test/src/commonMain/resources/testdata/

The Files are still there, just renamed:

The Attachments are used as a generic way to store additional data in the ast tree, for example line numbers or comments.

The main problem with comments is that they do not have a syntax relationship to the commented code, so you have to look at different places. This is "only" a ast parsing library, but assignment of comments to commented objects or assigning types to packages (by looking into import statements) is a task that should better be done by a compiler or documentation parser tool (that can use the ast from here, or can even be an extension of this library)

// comment 0
//val noCode = "part of someVal comments?"

// comment 1
/* comment 2 */
/** comment 3 */
val /* comment 4 */ someVal /* comment 5 */ = "try to lookup the comments in the ast"

kotlinx / ast

Question: Support for kdoc #17