Add standard comment header to each file

[gerth2]

We're a bit inconsistsant with how our headers look now Ensure each code file has a consistant header which include the following data:

Robot Casserole Common Libraries Year(s) developed Class name description any other info already in header Change log

[imdunne8]

We should leave out change logs from headers/comments. That's what version control is for. Descriptions/documentation within a comment header should be kept very short. If more than a few sentences are needed it should be made into a wiki page or a documentation page included in the repo.

[gerth2]

Fine by me. I derived that list from my employer's C code standards, which definitely do not cover the same exact space we do :)

On Thu, May 12, 2016 at 9:28 AM, Nick Dunne notifications@github.com wrote:

We should leave out change logs from headers/comments. That's what version control is for. Descriptions/documentation within a comment header should be kept very short. If more than a few sentences are needed it should be made into a wiki page or a documentation page included in the repo.

— You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub https://github.com/RobotCasserole1736/CasseroleLib/issues/4#issuecomment-218774586

[gerth2]

Even better, let's scope creep this (for a good cause):

http://www.javapractices.com/topic/TopicAction.do?Id=60

Update all files to have proper javadoc syntax. It will make any user feel warm and fuzzy that this is good software!

On Thu, May 12, 2016 at 11:58 AM, Chris Gerth chrisgerth010592@gmail.com wrote:

Fine by me. I derived that list from my employer's C code standards, which definitely do not cover the same exact space we do :)

On Thu, May 12, 2016 at 9:28 AM, Nick Dunne notifications@github.com wrote:

We should leave out change logs from headers/comments. That's what version control is for. Descriptions/documentation within a comment header should be kept very short. If more than a few sentences are needed it should be made into a wiki page or a documentation page included in the repo.

— You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub https://github.com/RobotCasserole1736/CasseroleLib/issues/4#issuecomment-218774586

[gerth2]

Bonus points: Publish the resulting javadoc to another folder in the repo to have some nice HTML reference pages for our software libraries

On Thu, May 12, 2016 at 12:00 PM, Chris Gerth chrisgerth010592@gmail.com wrote:

Even better, let's scope creep this (for a good cause):

http://www.javapractices.com/topic/TopicAction.do?Id=60

Update all files to have proper javadoc syntax. It will make any user feel warm and fuzzy that this is good software!

On Thu, May 12, 2016 at 11:58 AM, Chris Gerth chrisgerth010592@gmail.com wrote:

Fine by me. I derived that list from my employer's C code standards, which definitely do not cover the same exact space we do :)

On Thu, May 12, 2016 at 9:28 AM, Nick Dunne notifications@github.com wrote:

We should leave out change logs from headers/comments. That's what version control is for. Descriptions/documentation within a comment header should be kept very short. If more than a few sentences are needed it should be made into a wiki page or a documentation page included in the repo.

— You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub https://github.com/RobotCasserole1736/CasseroleLib/issues/4#issuecomment-218774586

[imdunne8]

I figured that last part was from working with old work code. Basically, if you look up anything about why people leave version history in the comments (while they're using version control) you'll find exactly your reason for about every case and nobody really has any other valid reason.

Anyways, JavaDoc would be nice for something like this where we expect that some other teams might want to use it. Eclipse creates the comment formatting for you automatically (put a /\ directly above a method or class and press enter) and there's a menu option to auto generate the HTML.

[gerth2]

So ran into weird things turning this into an eclipse project. For now, just adding the javadoc and added a batch file to update the html in the repo. By merging & pushing to the special gh-pages branch, the docs are automatically hosted on github (linked in the wiki)