HIPL

Doxy Readability / License Format

Asked by Stefan Götz

For example in http://infrahip.hiit.fi/hipl/doxygen/cache__port_8c.html, one needs to be blessed with exceptional eyesight to spot that there is indeed some file documentation behind the license statement.

So 1) the licencse obfuscates real documentation and 2) it unnecessarily litters the doxygen docs (I guess it is not the intention to GPL the docs, too?)

Would it make sense to make the actual documentation more readable and re-arrange the license statement to not be a doxygen comment? How about turning the license statement into // comments and follow it with the existing /** */ doxygen file documentation?

Question information

Language:
English Edit question
Status:
Answered
For:
HIPL Edit question
Assignee:
No assignee Edit question
Last query:
Last reply:
Revision history for this message
Christof Mroz (christof-mroz) said : 		#1

+1 for the // method from me.

Revision history for this message
Andrius Bentkus (toxedvirus) said : 		#2

Editing all files? Seems like a world of pain to me :)

Revision history for this message
Andrius Bentkus (toxedvirus) said : 		#3

Of course if done by a tool this would dramatically decrease the investment of work, still going through all files and looking for tool malfunctions would be necessary.

Since the comments were created by human hands there will be some irregularity we will have to deal with.

Revision history for this message
Stefan Götz (stefan.goetz-deactivatedaccount) said : 		#4

Hrm, you're right, that might be fairly annyoing, but I think it's manageable and I would do the work.

Could we get a go from one of the senior hipl developers for the basic idea?

Revision history for this message
René Hummen (rene-hummen) said : 		#5

I would suggest replacing "/** @file" (should always be the first line) in each file by "/*" and adding

"*/

/** @file"

right after the license statement. This should exclude the license statement from doxygen and keep doxygen comments intact.

Revision history for this message
Stefan Götz (stefan.goetz-deactivatedaccount) said : 		#6

Ok. I went for the // comments because the /* */ comments make it very easy for someone, who doesn't know the reasoning behind this, to put the license back into doxygen by oversight or semi-smartness. But if that concern is not shared, /* */ will certainly do the job. Any comments?

Revision history for this message
Miika Komu (miika-iki) said : 		#7

Fine by me. Rene, are you going to apply some awk magic?

Andrius, I think this shouldn't introduce conflicts to other branches.

Revision history for this message
Diego Biurrun (diego-biurrun) said : 		#8

I just separated all license boilerplates from Doxygen comment blocks.

Can you help with this problem?

Provide an answer of your own, or ask Stefan Götz for more information if necessary.

To post a message you must log in.