1. Idea for documentation makeover
- Posted by _tom (admin) Nov 16, 2012
- 1128 views
- An idea for a documentation makeover. This look can be achieved without rewriting the current documentation.
cmd_parse
parses command line options and optionally calls procedures based on these options.
cmd_parse( S1opts , O2parse_options = {} , S3cmds = command_line() )
include cmdline.e namespace cmdline public function
Arguments:
- S1 opts
- a sequence of records that define the various command line switches and options that are valid for the application: See Comments: section for details
- O2 parse_options = {}
- an optional list of special behavior modifiers: See Parse Options section for details
- S3 cmds = command_line()
- an optional sequence of command line arguments. If omitted the output from command_line is used.
- This is how the documentation looks currently.
cmd_parse
include cmdline.e namespace cmdline public function cmd_parse(sequence opts, object parse_options = {}, sequence cmds = command_line())
parses command line options and optionally calls procedures based on these options.
Parameters:
- opts : a sequence of records that define the various command line switches and options that are valid for the application: See Comments: section for details
- parse_options : an optional list of special behavior modifiers: See Parse Options section for details
- cmds : an optional sequence of command line arguments. If omitted the output from command_line is used.
- Any ideas or suggestions?
TOM
2. Re: Idea for documentation makeover
- Posted by mattlewis (admin) Nov 16, 2012
- 1086 views
- An idea for a documentation makeover. This look can be achieved without rewriting the current documentation.
cmd_parse
parses command line options and optionally calls procedures based on these options.
cmd_parse( S1opts , O2parse_options = {} , S3cmds = command_line() )
include cmdline.e namespace cmdline public function
Arguments:
- S1 opts
- a sequence of records that define the various command line switches and options that are valid for the application: See Comments: section for details
- O2 parse_options = {}
- an optional list of special behavior modifiers: See Parse Options section for details
- S3 cmds = command_line()
- an optional sequence of command line arguments. If omitted the output from command_line is used.
- Any ideas or suggestions?
I'm not a fan of the O2 / subscript stuff. I guess those are stand ins for object and sequence? What happens when a parameter is a UDT?
Matt
3. Re: Idea for documentation makeover
- Posted by _tom (admin) Nov 16, 2012
- 1114 views
The O S A I ( or o s a i ) are like the old RDS documents. (A bit of nostalgia here.)
The advantage of this style is it is easier to put the entire signature on one line.
If the parameter list contains a typedef then it could look like:
public function seek(file_number fn, file_position pos)
possible alternative:
public function seek( file_numberfn , file_positionpos )
Again, this does not require a rewrite of the documentation.
4. Re: Idea for documentation makeover
- Posted by K_D_R Nov 17, 2012
- 1022 views
The O S A I ( or o s a i ) are like the old RDS documents. (A bit of nostalgia here.)
The advantage of this style is it is easier to put the entire signature on one line.
If the parameter list contains a typedef then it could look like:
public function seek(file_number fn, file_position pos)
possible alternative:
public function seek( file_numberfn , file_positionpos )
Again, this does not require a rewrite of the documentation.
The style of documentation "makeover" you are recommending may make it easier to put a "signature" on one line, but the current method of documentation is much easier to understand. Euphoria "beginners" may be put off by having to learn a notational code in order to understand the language documentation.
Indeed, it seems that the goal of your documentation style is not to improve the quality of the documentation in any way, but only to symbolically compress descriptive statements.
If it is not broke, don't fix it.
Kenneth Rhodes
5. Re: Idea for documentation makeover
- Posted by petelomax Nov 17, 2012
- 1001 views
There *must* be better ways to waste your time.
