Skip to content
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.

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

Add support for @code inline comment tag. #475

Open
InsertCreativityHere opened this issue Mar 1, 2023 · 3 comments
Open

Add support for @code inline comment tag. #475

InsertCreativityHere opened this issue Mar 1, 2023 · 3 comments

Comments

@InsertCreativityHere
Copy link
Member

Like @externl pointed out, we frequently use <c> and <code> xml tags in our doc comments to format something as code,
but the slice compiler just treats that like raw text. It just happens to work because it means something to C# and currently, we only support C#. We should add a real tag for code snippets into the comment language like was suggested:
icerpc/icerpc-csharp#2728 (comment)

@InsertCreativityHere
Copy link
Member Author

InsertCreativityHere commented Mar 1, 2023

How exactly would this work? And would we allow multi-line code snippets too?

I think having {@code: x+1} works fine for small inline code snippets, but I don't think it would look good over multiple lines.
(The comment parser also disallows inline tags spanning multiple lines, but we can probably relax that).
The downside is that's kind of unergonomic.

We could also just support standard markdown code syntax like: `x+1` and ```x+1```
It would be more ergonomic, but would look less like how the rest of our tags work.

@pepone
Copy link
Member

pepone commented Mar 1, 2023

Not sure we need multi-line code snippets, Slice comments are copied over to the generated code, what language would you use in these snippets when targeting multiple languages?

@InsertCreativityHere
Copy link
Member Author

I also don't think multiline would be very useful; just wanted to gauge everyone else's thoughts.

So this Slice would get mapped as follows:

/// Next we compute {@code: x+1} and check it.

Generated C#:

/// Next we compute <c>x+1</c> and check it.

Generated Rust:

/// Next we compute `x+1` and check it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants