Hosting Doxygen docs (Re: [sldev] Doxygen & Comments)

[Gary Wardell]

>
> Usually, in my experience, when you put notes
> and codes in different places, what you get quite
> quickly are two things entirely out of sync.

And usually it's the location that requires extra effort to go to.

>
>
> Phoenix wrote:
>  > * comments in headers which describe
>  > ** parameters
>  > ** valid parameter ranges
>  > ** if parameter ranges are checked
>  > ** return value
>  >
>  > * comments in code which describe
>  > ** why a tricky and non-obvious is not written for clarity
>  > ** what a tricky and non-obvious tangle of code does
>
> Of all those, I'd only need the 2nd part.
>

Yes, but I'd also include a short definition of the parameters, like maybe what each is for.

Parameter ranges should be obvious from asserts and thus self documenting.

I also agree with the person that said it should be standardized.

Also, the comments should not simply restate the code or what is obvious form the code, they should add some insight as to what
the code is doing, otherwise they are a waste of resources.

Gary