[
http://opencast.jira.com/browse/MH-6952?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=26061#comment-26061
]
Kenneth Lui commented on MH-6952:
---------------------------------
I am not sure where these should go, maybe they should be created as separate
sub-tasks? I am writing them here in case I may lose track of what to do next.
It seems everyone is satisfied with my last patch. There are 2 more features
that we may want to implement. I have another suggestion as well.
1) A better table of content page for REST documentation.
2) Sample of the output in @RestResponse
My suggestion is inspired by #1. I think at the top of each service's
documentation page, there should be a mini "table of content" for that page
which consists of internal links that jump to the portion for each endpoint.
1) A better table of content page for REST documentation.
I am quoting our IRC conversation here for easy reference.
<kenneth__> rest_docs.html page is basically a copy of the welcome page, with
other information removed...I changed the doc links too.
<jholtzman> great
<kenneth__> For search, do you mean that I may type a endpoint name (e.g.
addTrack) and it will tell me which service (ingest) it is in?
<jholtzman> here's what I'm imagining:
<jholtzman> 1) calling a /service/docs.html returns a full html page for that
service
<jholtzman> 2) calling /service/docs.html?fragment=true (or something similar)
returns the same document, only without everything before and including <body>
<jholtzman> and of course stripping off </body>, etc
<jholtzman> 3) the table of contents can load each endpoint's fragment document
<jholtzman> and can show the doc in a div, can search all of the text across
each endpoint, etc
<jholtzman> so if I typed "mediapackage", I'd see which endpoints include that
word in their docs
<jholtzman> and those endpoint would be highlighted
<jholtzman> something like that
<jholtzman> this is all just nice to have... not required by any stretch, but
it would be really nice, IMO
If I understand it correctly, do you mean concatenating the body of every
service's documentation in the table of content? Would it be too long and
overwhelming? Please correct me if you meant something else.
Here is what I am imagining for a table of content..The table of content has a
tree like structure. The first level is what we are seeing now - all the
services. Each service can be expanded to show the endpoints in it. Each
endpoint can be further expanded to show the description. At this level, there
will be a link to link directly to this endpoint's portion in the "main"
documentation page. For searching, all tree "nodes" containing the searched
keyword will be expanded and the keyword will be highlighted. I think
"components.json" can be used to retrieve these info. I am not sure how
searching can be done, maybe using solr?
2) Sample of the output in @RestResponse
This is suggested by Josh in http://opencast.jira.com/source/cru/CR-MH-197#c625
. But what does "sample of output" mean? I have looked at "?_wadl&_type=xml".
For response, it only gives the MIME type documented by the @Produces
annotation. So I agree that it is not very informative. @RestResponse is
currently storing only the HTTP response code and a description. If more info
is to be added, would that be a XML schema, a json structure or something else?
Should that be in the form of String or some other more general object? What
information do developers expect?
> Update the ingest rest endpoint to use these new annotations as an example
> --------------------------------------------------------------------------
>
> Key: MH-6952
> URL: http://opencast.jira.com/browse/MH-6952
> Project: Matterhorn Project
> Issue Type: Sub-Task
> Components: Administrative Tools, Architecture & Services
> Affects Versions: 1.2
> Reporter: Christopher Brooks
> Assignee: Kenneth Lui
> Fix For: 1.2
>
> Attachments: mh6952v1.diff, mh6952v2.diff, mh6952v3.diff,
> mh6952v4.diff
>
>
> Kenneth, check out the ingest service endpoints and modify them to use this
> new code. This can serve as a demonstration of what we would like, and would
> give a nice contextualized example of how things should work.
--
This message is automatically generated by JIRA.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
_______________________________________________
Matterhorn mailing list
[email protected]
http://lists.opencastproject.org/mailman/listinfo/matterhorn
To unsubscribe please email
[email protected]
_______________________________________________
