icerpc / slicec

The Slice compiler library
Apache License 2.0
13 stars 5 forks source link

Add support for `@code` inline comment tag. #475

Open InsertCreativityHere opened 1 year ago

InsertCreativityHere commented 1 year ago

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: https://github.com/zeroc-ice/icerpc-csharp/pull/2728#discussion_r1121938213

InsertCreativityHere commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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.