Scite Javadoc Comment

wiki

--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--

--                                                                            --

-- Greetings, SciTE-user.                                                     --

-- This script is a little helper to create and maintain javadoc-style        --

-- comments. It works like the commenter in Eclipse; i.e.                     --

-- If you put                                                                 --

-- /**|                                                                       --

-- and press Enter (the | indicates where the cursor is located), you get     --

-- /**                                                                        --

--  * |                                                                       --

--  */                                                                        --

--                                                                            --

-- When pressing Enter in the situation                                       --

--     /**                                                                    --

--      * One Bourbon, One Scotch, One Beer|                                  --

--      */                                                                    --

-- you get                                                                    --

--     /**                                                                    --

--      * One Bourbon, One Scotch, One Beer                                   --

--      * |                                                                   --

--      */                                                                    --

--                                                                            --

-- There is also a setting javadoc_find_params, which will find parameters    --

-- for a function; e.g.                                                       --

-- /**|                                                                       --

-- bool born(int under, char *a="a bad", array sign) {                        --

-- }                                                                          --

-- will evaluate to                                                           --

-- /**                                                                        --

--  *                                                                         --

--  * @param under                                                            --

--  * @param *a (default: "a bad")                                            --

--  * @param sign                                                             --

--  * @return                                                                 --

--  */                                                                        --

-- bool born(int under, char *a="a bad", array sign) {                        --

-- }                                                                          --

-- It check for an opening bracket, and then considers every text between     --

-- commas as a parameter; if there is a space, then the first word is         --

-- considered the type.                                                       --

--                                                                            --

-- for any comments, suggestions or bugs etc, feel free to mail me at         --

-- jerous (a.t.) gmail.com                                                    --

--                                                                            --

-- I hope it is usefull for you,                                              --

-- jerous.                                                                    --

--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--





--~ determines if the script should try to find parameters, and add them to

--~ the comment. It will only look for them, if you put the cursor on 1 line

--~ before the function declaration.

javadoc_find_params = true



--~ create and maintain javadoc comments

--~ note: won't work correctly if the comment starts at the first line

--~ so just move it to the second line, and everything is ok!

function OnChar(c)

	expand = "/**"

	if c~="\n" then

		return false

	end

	

	-- are we creating a new comment?

	if editor:textrange(editor.CurrentPos-string.len(expand)-1, editor.CurrentPos-1)==expand then

		-- check here first if we create

		-- if modify, then skip over to the next if where we continue a comment

		-- we suppose if the next line starts with "*" it is a valid comment

		next_line = editor:GetLine(editor:LineFromPosition(editor.CurrentPos)+1)

		if next_line==nil or string.find(next_line, "^%s*%*")==nil then		

			prev_line = editor:GetLine(editor:LineFromPosition(editor.CurrentPos)-1)

			t1,t2,indent = string.find(prev_line, "^(%s*)")

			

			insert = indent.." * \n"

			inserted = false

			

			if next_line ~= nil and javadoc_find_params==true then

				-- here we try to retrieve the function's parameters!

				balance=0

				pos=editor:PositionFromLine(editor:LineFromPosition(editor.CurrentPos)+1)

				

				-- see if there is a "(" on the following line; if not, then

				-- we just create an empty comment

				while char_at(pos)~="(" and char_at(pos)~="\n" and pos<editor.Length do

					pos = pos+1

				end

				

				if char_at(pos)=="(" then

					param = ""

					pos = pos+1

					

					while (char_at(pos)~=")" or balance~=0) and pos<editor.Length do

						if char_at(pos)=="," and balance==0 then

							insert = insert..process_param(param, indent)

							param = ""

							pos=pos+1

							-- skip whitespaces after ","

							while char_at(pos)==" " do

								pos=pos+1

							end 

						end

						if char_at(pos)=="(" then

							balance = balance+1

						end

						if char_at(pos)==")" then

							balance = balance-1

						end

						param = param..char_at(pos)

						pos=pos+1

					end

					

					insert=insert..process_param(param, indent)..indent.." * @return \n"..indent.." */"

					inserted=true

				end

			end

	

			if javadoc_find_params==false or inserted==false then

				insert = insert..indent.." */"

			end

			

			editor:insert(-1, insert)

			-- position at the end of the line

			editor:GotoPos(editor.LineEndPosition[editor:LineFromPosition(editor.CurrentPos)])

			return

		end

	end

	

	-- are we continuing a comment?

	i = editor:LineFromPosition(editor.CurrentPos)-1

	while i>0 do

		line = editor:GetLine(i)

		i = i-1

		

		if string.find(line, "^%s*%*/") then

			break

		end

		

		if string.find(line, "^(%s*)/%*%*")~=nil then

			-- now we're sure we're processing a javadoc comment!

			-- so insert a new line!

		

			prev_line = editor:GetLine(editor:LineFromPosition(editor.CurrentPos)-1)

			t1,t2,indent = string.find(prev_line, "^(%s*)%*")

			if indent==nil then

				t1,t2,indent=string.find(prev_line, "^(%s*)")

				indent = indent .. " "

			end

			editor:insert(-1, indent.."* ")

			

			-- position at the end of the line

			editor:GotoPos(editor.LineEndPosition[editor:LineFromPosition(editor.CurrentPos)])

			break

		end



		if string.find(line, "^%s*%*")==nil then

			-- we're not inside a comment

			-- abort the mission

			break

		end

	end

end





function process_param(param, indent)

	if param=="" then

		return ""

	end

	default=""

	insert=""

	-- if there is a space, we suppose the first word is the type

	-- so we omit that!

	t1,t2,t3,param=string.find(param, "^([a-zA-Z_0-9&\*]* )(.*)$")

	

	-- check if there is a default, indicated by "param=value"

	if string.find(param, "=",0,true)~=nil then

		t1,t2,param,default=string.find(param, "^(.-)=(.*)$")

	end

	

	insert = insert..indent.." * @param "..param

	if default~="" then

		insert = insert .. " (default: "..default..")"

	end

	insert = insert.."\n"

	

	return insert

end



-- returns the character at position p as a string

function char_at(p)

	return string.char(editor.CharAt[p])

end