joffrey-bion
commented
6 years ago Some ideas for Livedoc IDs:
- make sure during the construction of the doc that every Livedoc ID is unique
- Livedoc IDs need to be good looking for users (displayed in the URL)
- Livedoc IDs need to be URL-valid
- allow overriding Livedoc IDs via annotations?
Some ideas for the anchor tags to act as livedoc links:
<a href="livedoc://type/{typeId}">Some Type</a>
<a href="livedoc://api/{apiId}">Some API</a>
<a href="livedoc://api/{apiId}/{operationId}">Some Operation</a>Break down of the feature:
- the UI should properly display a router
Linkfor the anchor tags mentioned above - provide macros for type/api/operation references in Freemarker templates
- add support for
@linktags to actually link to types/apis/operations
Is your feature request related to a problem? Please describe. It's frustrating not to be able to link to documentation elements from the free text global pages, nor from the descriptions of any element. The ability to do so would make the "flows" feature almost irrelevant (https://github.com/joffrey-bion/livedoc/issues/112), cleaning up a rotting feature, and make Livedoc more powerful overall.
Describe the solution you'd like We first need a special way to encode a link to an doc element in HTML values appearing in the JSON doc, probably using their Livedoc ID. Then, client side, it'd be possible to deal with this special convention thanks to the
react-active-htmlthat's already in use in the websocket feature branch. For instance, the HTML could look like:What I like about this is that the
<a>tag, if not interpreted correctly, would just be like a dead link, but would keep the text nice.Server side, links to methods or types in any Javadoc could be replaced by Livedoc using the special convention mentioned above, thanks to our custom
CommentFormatter, thus creating links in any doc element's description.For usage in Freemarker templates, we probably would have to expose the Livedoc ID convention to the users. This is not necessarily a bad idea, but could cause compatibility problems, so we'd better get that right the first time. Maybe some sort of custom macro/function could be used to make it less verbose on user side, but generate the HTML mentioned above anyway.
The Livedoc ID convention is already on this way, but needs to be refined.
Describe alternatives you've considered I don't see any alternative for now, since any user-defined content would require to know the routing format in the UI, which is not nice.