Skip to content

TypeSpec: new parser #4243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

TypeSpec: new parser #4243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Units/parser-typespec.r/simple-typespec.d/args.ctags
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
--sort=no
11 changes: 11 additions & 0 deletions Units/parser-typespec.r/simple-typespec.d/expected.tags
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Name.Space input.tsp /^namespace Name.Space;$/;" n
Versions input.tsp /^enum Versions {$/;" g
OpA input.tsp /^op OpA<T extends TypeSpec.Reflection.Model> is OpB<$/;" o
InterfaceA input.tsp /^interface InterfaceA extends InterfaceB {$/;" i
opA input.tsp /^ opA is OpA<{$/;" p interface:InterfaceA
opB input.tsp /^ opB: url;$/;" p interface:InterfaceA
UnionA input.tsp /^union UnionA {$/;" u
ModelA input.tsp /^model ModelA {$/;" m
contentA input.tsp /^ contentA: ModelB;$/;" p model:ModelA
contentB input.tsp /^ contentB?: boolean;$/;" p model:ModelA
AliasA input.tsp /^alias AliasA<$/;" a
83 changes: 83 additions & 0 deletions Units/parser-typespec.r/simple-typespec.d/input.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
import "@typespec/http";
import "./common.tsp";

using TypeSpec;
using TypeSpec.Rest;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm interested in extracting imported items and usinged items.
I will work on them after merging this pull request.

#3906
#2428


@armProviderNamespace
@service(#{ title: "Name.Space" })
@versioned(Versions)
@armCommonTypesVersion(CommonTypes.Versions.v3)
namespace Name.Space;

@doc("API Versions")
enum Versions {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we fill the scope: field of Versions with Name.Space?
(This comment applies to the other extractions.)

  • No, TypeSpec is not such a language,
  • Yes, "I'm interested in implementing it in this pull request", or
  • Yes, but someone will fix it in the future.

If you're interested in implementing it in this pull request, talk to me. I have some hints.
Of course, "Yes, but someone ..." is acceptable.

Let's call the above three items NYY-choice.

@doc("May 01, 2024 Preview API Version")
v2024_05_01_preview: "2024-05-01-preview",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we extract v2024_05_01_preview ?

NYY-choice.

}

@summary("Example operation summary for demonstration purposes.")
@doc("""
Example
multi-line
documentation.
""")
@returnsDoc("Example return documentation")
@post
op OpA<T extends TypeSpec.Reflection.Model> is OpB<
T & ModelA,
ModelB<ModelA[]>
>;

interface InterfaceA extends InterfaceB {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can fill inherits: field of interfaceA: with InterfaceB.
NYY-choice.

Filling such a field makes your work applicable to broader use cases.

Here is an example of C++.

$ cat /tmp/foo.cc 
class A: B {
	int x;
};
$ ./ctags -o - /tmp/foo.cc
A	/tmp/foo.cc	/^class A: B {$/;"	c	file:
x	/tmp/foo.cc	/^	int x;$/;"	m	class:A	typeref:typename:int	file:
$ ./ctags --fields=+i -o - /tmp/foo.cc
A	/tmp/foo.cc	/^class A: B {$/;"	c	file:	inherits:B
x	/tmp/foo.cc	/^	int x;$/;"	m	class:A	typeref:typename:int	file:
$ ./ctags --fields=+i -o foo.tags /tmp/foo.cc
$ ~/bin/querytags --tag-file foo.tags class-hierarchy  A
  A
   B

opA is OpA<{
@doc("The format of the HTTP payload.")
@header
contentType: "application/json";

@clientName("uri", "csharp")
@doc("Example URL parameter.")
opB: url;
}>;

/**
* Example operation description
*/
opB is OpB<
ModelA,
{
...ModelB
}
>;
}

@doc("Example union type description.")
union UnionA {
string,

@doc("Example option A description with some technical details that would be typical for this kind of documentation.")
"unionA",

@doc("Example option B description with additional technical context that would be common in API documentation.")
"unionB",
}

@doc("Example model description.")
model ModelA {
@doc("Example property description.")
contentA: ModelB;

@removed(Versions.v1_2)
@doc("Example boolean property with typical documentation about its purpose and default behavior.")
contentB?: boolean;

...ModelX;
}


alias AliasA<
TParamA extends ModelX,
TParamB,
TParamC extends ModelX = {},
TError = Error
> = ModelB<TParamA, TParamB, TParamC, TError>;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's increase the testing coverage, though. We don't have a target percentage.

E.g., the code skipping

 // comment

is not tested at all.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

String literal including \ is not converted.

1 change: 1 addition & 0 deletions main/parsers_p.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,7 @@
TTCNParser, \
Txt2tagsParser, \
TypeScriptParser, \
TypeSpecParser, \
VParser, \
VeraParser, \
VerilogParser, \
Expand Down
Loading
Loading