Initial pass to improve token documentation #5
Conversation
| /// <description>GroupId: `doc` to group consecutive comment tokens as documentation.</description> | ||
| /// </item> | ||
| /// <item> | ||
| /// <description>NavigateToId: Id for navigating to where the node where the token is defined. Should match the definitionId of the referenced node.</description> |
There was a problem hiding this comment.
@chidozieononiwu should this be should match the Id of the referenced node instead of definitionId ?
There was a problem hiding this comment.
Perhaps: "When the token is clicked, will navigate to the location that matches the provided token id."
| TabSpace = 3, | ||
| /// <summary> | ||
| /// Use this between method parameters. Depending on user setting this would result in a single space or new line. |
There was a problem hiding this comment.
I'm not sure what this "user setting" is that it refers to. Is this an existing feature I'm not aware of? If it renders a newline, does it also indent? Are the separate lines commentable? In Python we break params onto separate lines, but we have to assign line IDs to each of them. Does that work here?
There was a problem hiding this comment.
This is needed to support a new request: to allow users control how parameters render (same line vs new line). We can have language defaults and also support the indentation. The separate lines will be cementable if it has tokens with ids on it.
| ParameterSeparator = 4, | ||
| /// <summary> | ||
| /// A url token should have `LinkText` property i.e `token.Properties["LinkText"]` and the url/link should be the token value. |
There was a problem hiding this comment.
This seems like a strange place to mention this. There should probably just be a section that describes how to craft URLs and provides the correct JSON structure (not the C# structure).
I feel like this documentation should just be "This token describes a URL. See (URL section)"
There was a problem hiding this comment.
@chidozieononiwu could you provide this information?
There was a problem hiding this comment.
"value" : "the url" "kind" : "Url", "Properties" : [ "LinkText" : "link text to display" ]
|
Update: I have addressed all comments that I have context about. For string vs enum vs extensible enum, we can leave those for the main PR. |
chidozieononiwu
force-pushed
the
feature/ImprovedTokens
branch
from
5f2bed0 to
daf0679
Compare
Parse C# Assemblly to Token Tree Add Token Tree Documentation Add LineDefinitionId and HideFromNavigation Undo internals visible to setting Sort NameSpaces and Types Ensure Each node has Name and Id Serialize to Message Pack Add Tags to StructuredToken update tree Token Parser Documentation Attempt to Improve Serialized JSON Size Properties for Serialization and Deserialization Use shorter names for diagnostics update APIView Parser Contributing guide Delete TreeTokenCodeFile Update APIView C# Parser Project Name Add MessagePack Serialization Switch to System.Json.Text working Update Contributing Doc Add Navigate to ID Make Parser a dotnet Tool Update Parser Version for CodeFile App Parser Style Property Output GZipped TokenFile Switch to Human Readable Json Property Names, use compression Fix some issues raised in pull request Updating Contributing.md Update Contributing Docs initial pass to documentation fix pr feedback one missed
chidozieononiwu
merged commit 513a046
into
chidozieononiwu:feature/ImprovedTokens
The main goal behind the PR is to use the classes as bases for documentation. I am mainly organizing information.
I don't intend to change code here. Comments related to code will be in original PR Azure#7980