[gobolinux-users] Gobo wants you! (to comment its scripts)

[Daniele Maccari]

Ok, I created a page on the wiki, I hope it will help :)

http://gobo.kundor.org/wiki/Code_Documentation_Project

As for the bash comments format, I don't have any real preference, but 
maybe trying to keep it consistent with python scripts' one would be 
nice, wouldn't it?

Aitor suggested a way to make them parseable and at the same time quite 
explanatory, any other idea here?

Here's his one:

Hi Danniele,
I was thinking in create a little script to parse files comments, at
least two kind of comments:

	* Comments to the code, wont be parsed
	* Comments describing exported functions or script programs, will be
	parsed

So we need a predefined format for comments that will be parsed:

Bash Functions Files:
	* A comment at the beginning telling what the file is intended to:

		File: file_name
		Description:
			Description of the file
		Usage:
			Usage
		[Other optional fields if you want, like dev creator, license
		...]

	* A comment in each function describing the funciont, with input and
	output and a some example usage

		Function: func_name
		Description:
			Description of the func
		Input:
			input1: desc
			input2: desc
		Output:
			output_desc

Bash Script Files:
	* Only comments at the beginning (the same format as Bash Functions
	Files), these files ussually don't export functions, so is not
	require to export that info.

Python (other scripts languages):
	* The same as Bash Script Files.

The script i have in mind will parse a file and could output a wiki
entry or a man page (or anyother format) from the file comments.

What do you think?

Thanks for your time :)

Aitor.