Hi,
> If you have anything written in the comments section of the explorer these
> are displayed instead (everyone should TURN OFF the automatic comment
> feature immediately).
I do use a lot of components and I love it.
I have been using automated documentation since v11/v12.
We all know technical documentation is a pain to write, maintain, etc...
This is especially true for Components where you need a documentation.
I got the idea from javadoc. Basically with javadoc, you use some tags in the
comments which are used by a tool to generate automatically technical
documentation.
Since v13, this can be done *seamlessly* with macros and new commands in 4D
v13...
Basically you create a new method, a tag comment section is inserted. You write
you code and fill-in the comment section.
When you save the method, the header is analyzed and parsed and the
documentation is generated in the "comment" section (it could also be exported
in xml, html, whatever)...
My method header looks like this :
//================================================================================
//@xdoc-start : en
//@name : S3_RestApi
//@scope : public
//@deprecated : no
//@description : This method will send a request to Amazon Web Services (AWS)
s3 web-service
//@parameter[0-OUT-httpReponseStatus-TEXT] : http repsonse status (e.g. 200)
//@parameter[1-IN-httpVerb-TEXT] : http verb ("GET", "POST", "PUT", "DELETE")
//@parameter[2-IN-bucket-TEXT] : bucket name (makes the host
"<bucket>.s3.amazonaws.com", e.g. "ac-consulting-test" =>
"ac-consulting-test.s3.amazonaws.com")
//@parameter[3-IN-uri-TEXT] : uri, url encoded (e.g. "/test/demo/image.png")
//@parameter[4-IN-httpRequestHeaderLinesPtr-POINTER] : request header lines
text array pointer (optional, not modified)
//@parameter[5-IN-httpRequestBodyBlobPtr-POINTER] : request body blob pointer
(optional, not modified)
//@parameter[6-OUT-httpResponseHeaderArrayPtr-POINTER] : response header
lines text array pointer (optional, modified)
//@parameter[7-OUT-httpResponseBodyBlobPtr-POINTER] : response body blob
pointer (optional, modified)
//@parameter[8-IN-contentType-TEXT] : content type (optional e.g. "image/png")
//@notes :
//@example : S3_RestApi
//@see :
//
http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html
//@version : 1.00.00
//@author : Bruno LEGAY (BLE) - Copyrights A&C Consulting - 2016
//@history : CREATION : Bruno LEGAY (BLE) - 23/03/2015, 15:24:54 - v1.00.00
//@xdoc-end
//================================================================================
If you want to see the result, you can check out the "aws compnent" I published
on github :
https://github.com/blegay/aws_component
I made a component to generate provide the macros, and generate the
documentation. Let me know if you are interested.
HTH
Bruno
**********************************************************************
4D Internet Users Group (4D iNUG)
FAQ: http://lists.4d.com/faqnug.html
Archive: http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub: mailto:[email protected]
**********************************************************************
