[ 
http://opencast.jira.com/browse/MH-6885?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=24871#comment-24871
 ] 

Kenneth Lui commented on MH-6885:
---------------------------------

I started doing some refactoring but encountered some issues.

I removed the Method enum for GET, POST, etc. and replaced it by using @GET, 
@POST, etc. This went okay.

When I tried to replace the Format class with @Produces, I realized it wasn't 
very straightforward.
The Format class contains the name, description and url of the format. I am 
thinking of using the value of @Produces (e.g. "text/xml") for the name. URL is 
rarely used but sometimes developers put a link for referencing. For example, 
in SchedulerRestService.java, there is 
getCalendarForCaptureAgentEndpoint.addFormat(new Format("ics", "iCalendar", 
"http://tools.ietf.org/html/rfc2445";));
I am suggesting that we can put 2 String fields in our RestQuery annotation, 
one is returnFormatDescription and one is returnFormatURL.
However, with @Produces, developers can put more than 1 value in it (i.e. put 
an array). So, @Produces({MediaType.TEXT_PLAIN, 
MediaType.APPLICATION_ATOM_XML}) is a possible to happen. I searched through 
the code and did not find any use of @Produces like that. But I am not sure 
whether I should assume this to always be the case.

There is also another related issue. Currently, an endpoint returning 2 formats 
of the same result is documented as 1 method. For example, "GET 
/{eventId}.{format}.{xml|json}" in "/scheduler/docs" is one method but it is in 
fact 2 java methods in the code (and with different @Produces value too). In 
our new documentation mechanism, it will be documented as 2 methods, is that a 
desired change?

Regarding the ExtendedMediaType suggestion, I think there needs to be 2 
constants. "image/jpeg" for jpeg and "text/calendar" for iCalendar. (See 
http://en.wikipedia.org/wiki/ICalendar). I cannot find the MIME type for 
".properties", I think "MediaType.TEXT_PLAIN" should be fine for now.

For the RestTestForm, it is quite flexible in the sense that you can either 1) 
let it generate the form for you (auto), or 2) supply a html string and use 
that instead of the auto generated test form, or 3) supply an url to a separate 
page and use the page instead of test auto generated test form.
However, I looked over the code and found that everyone is using the auto mode. 
At this moment, I would suggest we always assume the form is auto generated and 
not create an annotation for it.

> Outline the steps to replace the old doc engine
> -----------------------------------------------
>
>                 Key: MH-6885
>                 URL: http://opencast.jira.com/browse/MH-6885
>             Project: Matterhorn Project
>          Issue Type: Sub-Task
>          Components: Architecture & Services
>    Affects Versions: 1.2
>            Reporter: Christopher Brooks
>            Assignee: Kenneth Lui
>             Fix For: 1.2
>
>         Attachments: mh6885v1.diff, restdocs.diff, restdocs.diff
>
>
> Now that we have a base template setup, what do we need to do to replace the 
> current docs system with this?  How are docs html being generated, and what 
> files from there do we need to bring into matterhorn kernel?

-- 
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]
_______________________________________________

Reply via email to