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

[Rob Lanphier]

Hi all,

On a tangent, if you all would like us to host a set of
Doxygen-generated comments, let us know, specifically by filing a task
in JIRA in the WEB project.  Since I'm a little fuzzy on where I'd put
said comments, I'm not sure when I'd personally get around to doing it,
but a JIRA task would be a handy reminder to get around to it.

Thanks
Rob

On 6/7/07 9:48 AM, Phoenix wrote:
> Regardless of international consumers of the code, the majority of
> english speaking devs that work on SL would benefit from:
>
> * 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
>
>
> On 2007 Jun 7, at 09:17, Dzonatas wrote:
>> Max Okumoto wrote:
>>> Would patches which add javadoc type comments to functions be
>>> welcome?  I usually add comments to code that I am trying to
>>> understand.
>>
>> The main problem with comments in code is that the comments are
>> usually in some sub-human form of English. The prose of the sub-human
>> language is insignificant to on the scale of readability and
>> communicative expression of the content it relates to the reader, or,
>> better yet, to the programmer. What matters more to the programmer is
>> the ability to communicate that content of that comment to the
>> intended audience. If the programmer desires to only to deal with an
>> audience that is able to read at least some form of sub-human
>> English, the comments will be written in that so stated English form.
>> The global world is much greater and diverse, and there are many
>> programmers that can barely translate English. The comments may be of
>> some interest to them, but it may be more of a pain in the ass in
>> their time to comprehend it than it is just to look straight at the
>> code. Also, there are more programmers out there that do not speak
>> any form of English. Those comments that are written in a form of
>> English are of no use to a programmer that does not speak any form of
>> English. In fact, the comments appear more like litter on the road
>> where you have to go pay some state or province tax to clean-up,
>> which such taxs funds are usually channeled through endless reams of
>> political red-tape until it ends up in the paycheck of a law
>> enforcement officer to watch over a community work project of less
>> fortunate group of sub-humans to complete the road service clean-up job.
>>
>> I could get into a debate over the amount of time is wasted in
>> comments, which are pieces of the source that have absolutely no
>> function to the end-user. There are obviously far better tools to
>> document source than in-line liter. Some of the most simplest issue
>> trackers make a better basis for a documentative system. If a
>> programmer thinks there is a need to create further documentation for
>> a class, then that programmer has done well to follow-up with a
>> tracker item for such reason and where such documentation will flow.
>> Do not take this mixture of documentation and tracker issue as the
>> only way or as the way that I suggest is best, as it is merely better
>> idea to give a programmer the fluidity to work focused on the code
>> itself than for that programmer to worry about foreign, sub-human
>> comments.
>>
>> Being able to program is like a fluid degree of skill at a foreign
>> language or any language, really. Skill with a program language
>> profoundly compares to skill with a foreign language. Does anybody
>> tell professional English writers that they must comment their books
>> and articles with C++? I didn't think so.
>>
>> Dz
>>
>> -- 
>> _______________________________________________
>> Click here to unsubscribe or manage your list subscription:
>> /index.html
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Click here to unsubscribe or manage your list subscription:
> /index.html
>   


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://lists.secondlife.com/pipermail/sldev/attachments/20070607/9cc7b805/signature.pgp