Added documentation to the operations and parameters

git-svn-id: https://develop.sub.uni-goettingen.de/repos/textgrid/trunk/services/aggregator@13897 7c539038-3410-0410-b1ec-0f2a7bf1c452

src/main/java/info/textgrid/services/aggregator/epub/EPUB.java

@@ -36,6 +36,8 @@
 import javax.ws.rs.core.Response.Status;
 import javax.xml.transform.stream.StreamSource;
 
+import org.apache.cxf.jaxrs.model.wadl.Description;
+
 import net.sf.saxon.s9api.Processor;
 import net.sf.saxon.s9api.SaxonApiException;
 import net.sf.saxon.s9api.XsltCompiler;
@@ -46,6 +48,7 @@
 import com.google.common.io.InputSupplier;
 
 @Path("/epub")
+@Description("Converts the given TEI object or the aggregation of TEI objects to an E-Book in EPUB format")
 public class EPUB {
 
 	private static final String EPUB_XSL = "/WEB-INF/stylesheets/epub.xsl";
@@ -96,9 +99,11 @@ public EPUB(final ITextGridRep repository) {
 	@GET
 	@Path(value = "/{object}")
 	@Produces(value = "application/epub+zip")
-	public Response get(@PathParam("object") final URI uri,
-			@QueryParam("stylesheet") final URI xsluri,
-			@QueryParam("sid") final String sid)
+	public Response get(
+			@Description("The TextGrid URI of the object to convert, either a TEI object or an aggregation of TEI (and maybe other) objects")
+			@PathParam("object") final URI uri,
+			@Description("URL of an alternative stylesheet to use. Must be compatible.") @QueryParam("stylesheet") final URI xsluri,
+			@Description("Session ID for accessing protected objects") @QueryParam("sid") final String sid)
 					throws ObjectNotFoundFault, MetadataParseFault, IoFault, AuthFault,
 					ProtocolNotImplementedFault {
 		logger.fine("EPUB called for root object: " + uri);

src/main/java/info/textgrid/services/aggregator/html/HTML.java

@@ -34,6 +34,8 @@
 import javax.ws.rs.core.StreamingOutput;
 import javax.xml.transform.stream.StreamSource;
 
+import org.apache.cxf.jaxrs.model.wadl.Description;
+
 import net.sf.saxon.s9api.Processor;
 import net.sf.saxon.s9api.QName;
 import net.sf.saxon.s9api.SaxonApiException;
@@ -45,6 +47,7 @@
 import com.google.common.io.FileBackedOutputStream;
 
 @Path("/html")
+@Description("Creates an HTML representation of the given TEI document, or aggregation of TEI documents. This is currently extremely experimental and probably broken.")
 public class HTML {
 
 
@@ -86,9 +89,14 @@ public HTML(final ITextGridRep repository) throws IOException {
 	@GET
 	@Path(value = "/{object}")
 	@Produces(value = "text/html")
-	public StreamingOutput get(@PathParam("object") final URI uri,
+	public StreamingOutput get(
+			@Description("The TextGrid URI of the TEI document or aggregation to transform")
+			@PathParam("object") final URI uri,
+			@Description("If given, an alternative XSLT stylesheet to use")
 			@QueryParam("stylesheet") final URI xsluri,
+			@Description("Session ID to access protected resources")
 			@QueryParam("sid") final String sid,
+			@Description("URL of the CSS that should be referenced in the HTML that is created")
 			@QueryParam("css") final URI css) throws ObjectNotFoundFault,
 			MetadataParseFault, IoFault, AuthFault,
 			ProtocolNotImplementedFault, WebApplicationException, IOException,

src/main/java/info/textgrid/services/aggregator/pdf/PDF.java

@@ -37,11 +37,16 @@
 import net.sf.saxon.s9api.XsltTransformer;
 
 import org.apache.commons.io.FileUtils;
+import org.apache.cxf.jaxrs.model.wadl.Description;
 
 import com.google.common.io.FileBackedOutputStream;
 import com.google.common.io.Files;
 
 @Path("/pdf")
+@Description("Generates a (default) PDF representation of a TEI document. " +
+		"This is currently highly experimental, and it requires LaTeX and " +
+		"the TEI stylesheets to be installed on the machine onto which " +
+		"this service is deployed.")
 public class PDF {
 
 	final Logger logger = Logger.getLogger("info.textgrid.services.aggregator");
@@ -64,8 +69,9 @@ public PDF(final ITextGridRep repository) {
 	@GET
 	@Path("/{uri}")
 	@Produces("application/pdf")
-	public Response get(@PathParam("uri") final URI uri,
-			@QueryParam("sid") final String sid) {
+	public Response get(
+			@Description("The TextGrid URI of a TEI document to transform") @PathParam("uri") final URI uri,
+			@Description("Session ID to access protected resources") @QueryParam("sid") final String sid) {
 		final File workingDir = Files.createTempDir();
 		try {
 

src/main/java/info/textgrid/services/aggregator/teicorpus/TEICorpus.java

@@ -27,6 +27,10 @@
 import javax.ws.rs.core.Response.ResponseBuilder;
 import javax.ws.rs.core.Response.Status;
 
+import org.apache.cxf.jaxrs.model.wadl.Description;
+import org.apache.cxf.jaxrs.model.wadl.Descriptions;
+import org.apache.cxf.jaxrs.model.wadl.DocTarget;
+
 /*
  * Generating a TEIcorpus document from a (single) aggregation
  * 
@@ -51,6 +55,7 @@
  * We could use this, so it's only one large request per aggregation. Should be
  * reasonably fast.
  */
+@Description("Creates a TEI corpus of all the TEI documents (recursively) aggregated by the given aggregation")
 @Path("/teicorpus")
 public class TEICorpus {
 
@@ -66,10 +71,14 @@ public TEICorpus(final ITextGridRep repository) {
 	@GET
 	@Path(value="/{aggregation}")
 	@Produces("text/xml")
-	public Response get(@PathParam("aggregation") final URI uri,
-			@QueryParam("attach") @DefaultValue("true") final boolean attach,
-			@QueryParam("flat") @DefaultValue("false") final boolean flat,
-			@QueryParam("sid") final String sid)
+	@Descriptions({
+			@Description(target=DocTarget.METHOD, value="Creates a TEI corpus of all the TEI documents (recursively) aggregated by the given aggregation"),
+			@Description(target=DocTarget.RETURN, value="TEI corpus document")
+	})
+	public Response get(@Description("TextGrid URI of the root aggregation") @PathParam("aggregation") final URI uri,
+			@Description("Whether to generate a Content-Disposition: attachment header") @QueryParam("attach") @DefaultValue("true") final boolean attach,
+			@Description("If true, no intermediate TEI corpus documents will be generated for intermediate aggregations, hierarchical structure will be lost") @QueryParam("flat") @DefaultValue("false") final boolean flat,
+			@Description("Session id for accessing restricted resources") @QueryParam("sid") final String sid)
 					throws URISyntaxException, ObjectNotFoundFault, MetadataParseFault, IoFault, AuthFault {
 		logger.fine("TEIcorpus called for root aggregation: " + uri);
 		final TGCrudService crud = repository.getCRUDService();