icerpc / icerpc-docs Goto Github PK

Unless I missed something the new Slice2 WellKnownTypes are not documented

We should not wrap a word on 2 lines like:

Customize the sequence and dictionar
y mapping.

See for example the C# attributes table.

How do we name anchors with markdown?

This is useful/needed when a heading contains a ' as in "IceRPC's preferred protocol".

Stripe does it:
https://stripe.com/docs/mobile/android/basic#collect-details

but it's not clear how.

This syntax does not work:
https://gerrit.googlesource.com/gitiles/+/refs/tags/v0.1-11/Documentation/markdown.md#Named-anchors

I think most of this section is incorrect.

Desired feature

I think would be an improvement if the site use the screen full width. Similar to what GitHub does now.

Problem

Alternatives

I think it would look nicer if we take advantage of the unused space in the left and right margins.

The page https://docs.testing.zeroc.com/getting-started/raising-the-bar/modular-rpc-for-quic has 2 mermaid diagrams and most of the time the second diagram gets inserted into the first, resulting in very bad display.

It's the very first page of our documentation, so pretty bad.

A few comments regarding Proxy documentation

On the Interface page, we have:

Such a field or parameter (etc.) represents the address of a remote service that implements this interface, and is called a proxy. Please refer to Proxy for details.

The proxy page doesn't clearly define what a proxy is.

It starts by talking about service addresses, and interfaces, but I think we should include something like what we have in interfaces pages that make this "interface/proxy" correspondence clear.

The WidgetFactory does not return a full-blown widget, but the address of the service it just created.

I think "created" is an implementation detail, which is irrelevant in Slice, so "..., but the address of the service."

We describe this situation as createWidget returns a Widget proxy.

I think is simpler to say "We say the createWidget operation returns a Widget proxy.

When the Slice engine decodes a relative proxy from an incoming request payload

That is correct, but wouldn't it be clear for the user if we present this in terms of dispatch parameters, and invocation return value?

You need to transform this proxy before you can use it to make requests.

Transform how?

this decoded proxy is ready to go. You don't need to transform it further before making calls with this proxy.

the decoded proxy is ready for making invocations to the target service.

How can I insert a diagram / image in the doc?

I want to insert an Excalidraw diagram in SVG format. The markdoc documentation suggests it's a built-in node but I can't get it to work.

https://markdoc.dev/docs/syntax

In standard Markdown, headers are requires for tables, but there are some tables where headers just aren't needed.
For example, I'm using a table to format lists of keywords, but there's no meaningful header to put on this table, despite it being required.

Is there a way to support markdown tables that don't have headers?
If this outside the realm of possibility, is there an alternative to Markdown tables I could use for this?

Nowhere on the enum page does it mention unchecked.
https://github.com/icerpc/icerpc-docs/blob/b0c5baae5b67ca46174f7990c7568a19dec583f5/pages/docs/slice/language-guide/enum-types.md

We use @vercel/og to generate open graph images that are used when links to the docs are posted around the web. Commonly these get seen in iMessage, twitter, etc as the images that show up when you share something.

We now support dynamically creating these images for each page. However, I did not but much work into the design for now. Before release we should make sure to update this.

Here is the current generated open graph image for https://docs.testing.zeroc.com/docs/slice/basics/contract-first

In https://docs.testing.zeroc.com/docs/slice/language-guide/interface#proxy we have a link to "relative-proxy" but doesn't point to any page. Seems like we need to add one.

See #33 (comment)

To me "features" is an IceRPC concept that we will provide with the different language mappings.

The current version of the doc uses few back quotes. Benoit's PR #30 adds lots of back quotes.

Clearly, we first need to decide when we should use back quotes.

I am not in favor of using lots of back quotes because they make the text harder to read (which could be in part a rendering issue).

It's very easy to lose the ?encoding=SliceX when clicking on various Slice pages.

It actually goes away more often than it stays.

Is there any we can use the standard VS code color scheme for C# syntax highlighting?

I don't see the point in inventing on our color scheme for C#.
C# developers are used to the VS code color scheme; ours currently looks much worse.

We should document the Slic protocol.

Using req.headers.host for local development correct returns the hostname and port localhost:XXXX. However, when hosted on the docker container it includes x-webdoc/.../hostname:port. This causes the links generated for the feedback emails to be unable to be opened.

This no longer works:

```
icerpc://hello.zeroc.com/hello?transport=quic
```

Some notes regarding

https://docs.testing.zeroc.com/docs/slice/basics/slice-components

The Slice language and the Slice encoding are programming language independent: a Slice string has always the same name and encoding regardless of the programming language (or languages) you use to make RPC calls and to implement the business logic of these RPCs.

I think the word name, in "the same name and encoding" gives the impression that our encoding includes the name of things.

I also find it uncommon to say Slice (the language) is programming language independent.

Slice library code

Maybe it is clear to use another term like "Slice encoding implementation"

We have two API endpoints currently. One for generating a dynamic, open graph image used for metadata and another for sending an email when feedback is received. Since we have no sessions/rate limiting, someone can spam these APIs to cause massive email spam.

We should consider adding some form of rate-limiting middleware to prevent this.

The GitHub footer link doesn't change from zeroc-ice to icerpc, when you change the product. The one in the header does.

Our Overview pages are not correct. The large title should (obviously) not be Overview!

It should be the section title (Getting Started, IceRPC Core etc.) but it should not be under a little title with the same words. Basically, we should do like Stripe doc, see for example:

https://stripe.com/docs/finance-automation

csharp: should add .html before the fragment and leave the fragment as is.

Example that should work but currently doesn't:

[features](csharp:IceRpc.IncomingRequest#IceRpc_IncomingRequest_Features)

See title.

Strangely this new slice option eats blank lines, e.g.

compact struct ServerAddressData {
    transportCode: TransportCode
    encapsulation: Encapsulation
}

compact struct Encapsulation {
    size: int32              // payload size + 6
    encodingMajor: uint8     // always 1
    encodingMinor: uint8     // always 1
    payload: uint8[...]      // pseudo-Slice
}

typealias TransportCode = int16

Currently, we always format our tables with horizontal bars dividing rows of elements, and nothing else.
This works well for certain circumstances, but not for a general purpose table.

It would be preferable to have some way of toggling the presence of vertical/horizontal bars.
There's one place where I'd like only vertical bars, and another place where I need a real table that has a proper grid.

The rendering of C# code blocks is poor:

• we should not use italics for anything
• the comments are barely readable
• there is no need to decorate the code block with the language name.

If at all possible, I would use the same rendering as GitHub, which looks much nicer:
https://github.com/zeroc-ice/icerpc-docs/blob/main/pages/docs/icerpc-core/connection/client-vs-server-connections.md

In light mode, we get colors but our use of the same blue for different meanings is confusing: it's both the color of links and titles.

In dark mode, it seems we use colors (blue) only for links which results in a pretty drab look.

Something is not right with anchors. In the attached screenshot, I used a link to go to #client-connection-configuration, and yet I was brought a little below on the page.

I think would make the reading easier if we remove the api marker

The 404 page is mostly empty, I think it would be good to keep at least the main header

I'm not sure how links/components work, but the idea would be to provide a way to link the reference documentation using the type name.

The [ClientConnection](csharp:IceRpc.ClientConnection)

And then this would render the actual link

The [ClientConnection](https://docs.testing.zeroc.com/docs/icerpc-core/invocation/invocation-pipeline)

We need to replace this diagram with a new Mermaid Zenuml diagram.

It's not clear how to use them. Where is the documentation?

How to reproduce:

with Slice2 selected, go to http://localhost:3000/docs/slice/language-guide/attributes#shared-attributes and click on slicedFormat hyperlink. This should bring you to http://localhost:3000/docs/slice/language-guide/class-types?encoding=Slice1#slicing

It works fine if you select "open new window" or "open new tab" But it doesn't work if you just click on the link: you get to the top of the class page, not the Slicing section

Please revert the updates to the VS code screenshots. They are now very hard to read. These screenshots should use the full width, just like they did previously.

Then I believe it would be more accurate to write "When the operation has a single return type", The way I see it, an operation has a return type, and it returns a value, which has a type matching the operation returns type.

Originally posted by @pepone in #54 (comment)

Should we use "an operation has a single return type" instead of "an operation returns a single type"?

https://docs.testing.zeroc.com/docs/slice/encoding/main-features#little-endian

On the other hand, the ice and icerpc protocols define their frame headers and control frames using Slice; this usage favors big-endian ordering.

We selected little-endian because Slice's main job is to encode/decode the payloads of requests and responses. Its use for the ice and icerpc frame headers is secondary. And it's simpler to use the same ordering (little-endian) in all situations.

What does it mean that it favors big-endian? To me, this sounds a bit like using big-endian for the protocol would be better, but we use little-endian because it is simpler to always use the same, which I don't think is the case.

The spellchecker job fails here:

Warning: Unknown word (parameterless)
pages/docs/slice/language-guide/interface.md:181:34 Unknown word (parameterless)
Files checked: 5, Issues found: 1 in 1 files.
Error: 1 spelling issue found in 1 of the 5 files checked.

This proposed syntax doesn't work with our doc setup:

The correct way to add comments in Markdown is like this:

<!-- TODO: add a link to 'identifiers::escaping' to the first paragraph -->

Originally posted by @ReeceHumphreys in #39 (comment)

Personally, I don't think this is necessary. The way I've always written markdown comments is: [comment]: <> (stuff) and that works perfectly fine for me. But I'm opening it anyways in case anyone else thinks we should add support for this.

We expect most potential users will start reading Getting started. So Getting started needs to be:

• informative
• not boring
• not repetitive
• correct

What do you see on Getting started page?

Get started with IceRPC - seriously?
Quick links (I opened another bug for this subtitle)
Check out an example project

The mermaid diagram rendering package had a major version release to 10.0. It would be good to migrate to it at some point in the future. Looks like it will take a bit of work though as they changed their API to async await.

A service address in IceRPC is not an arbitrary URI. Its protocol must be ice, icerpc or null (i.e. a relative service address).

We should add a Compiler diagnostics section that lists the errors and warnings that slicec-cs can emit.

For each error and warning, we should provide an explanation (more than the message) and when appropriate provide an example.

The removal of {% title %} introduced too many blank lines, e.g.

---
title: Client vs server connections
description: Learn how to create and accept connections in IceRPC.
---



## What are connections for?

I added this because spell check job was failing,

data\icerpc-core-data.ts
140:        path: `${RPC_CORE_BASE_URL}/icerpc-protocol/mapping-rpcs-to-streams

Originally posted by @pepone in #40 (comment)

We should not have any "Quick links" subtitles. It makes no sense.

If you look at the model - Stripe docs - there is no Quick links subtitle anywhere.

The correct layout is meaningful subtitle followed by cards.

https://stripe.com/docs