search

cuelang / cue

CUE has moved to https://github.com/cue-lang/cue
https://cuelang.org
Apache License 2.0
3.09k stars 171 forks source link

cmd/cue: add doc command #998

Closed myitcv closed 3 years ago

myitcv commented 3 years ago

This has been discussed many times in passing in other issues/discussions/Slack messages; creating an issue to track the addition of a cue doc command.

Would be similar in nature to go doc

jugaadi commented 3 years ago

JSON Schema supports annotations like title, description and comments while OpenAPI(v3.1) supports summary, and tags along with existing JSON Schema annotations.

A special attribute for documentation like @doc would be helpful to resolve the doc metadata as well as the multiline docstring(or comment) below it.

myitcv commented 3 years ago

@jugaadi - can you explain what you are trying to achieve here? Because it sounds like you are trying to extract documentation about certain identifiers/packages? That being the case, I suspect working with cue/ast is what you are after. Or alternatively, cue.Value.Doc() depending on how you are working with CUE.

jugaadi commented 3 years ago

Sorry for the misunderstanding.. Actually I was just stating my requirement for the feature. Just like JSONSchema/OpenAPI support all these constructs for documentation, it would be really helpful if cue docs support more than just line comments. For example, OpenAPI description fields support CommonMark formatting to render rich text in the generated docs.

In order to do this, I was wondering whether an attribute(@doc) is the right way to go about it so that doc tooling can take advantage of additional metadata that can be passed along with it.

cueckoo commented 3 years ago

This issue has been migrated to https://github.com/cue-lang/cue/issues/998.

For more details about CUE's migration to a new home, please see https://github.com/cue-lang/cue/issues/1078.