I have read some stupid shit on here but that is the absolute stupides in quite a while.
XML is perfect for creating a markeup to markup comments in every way. To think otherwise means you really don't understand anything about this topic.
Structured comments solve a non-problem; Extracting useful documentation directly from the source code is useless if there isn't any useful documentation directly in the source code.
There are a large number of nearly empty javadoc and doxygens published on the Internet. Worthless documentation isn't better than no-documentation. At least with the latter it's harder to delude yourself into thinking you've got something. That means autodocumentation tools are simply making things worse.
Good documentation, means prose, not property lists on program definitions. XML simply doesn't enter into it.
Oh wow. More stupididty.
You arguement is meaningless. XML markup of comments has nothing to do with the quality of those comments.
Bad comments are bad. Good comments are good. Good comments with meaningful markup are better.
Comments don't suddenly become bad when you add extra meaningful information to them that identifies exactly what the comment is for.
If you can't see why the ability to have a standard meaningful way to document a function paramter is a good thing, you need to stop "programming." If your comments aren't good enough to provide even basic useful documnetation, then you suck at commenting.
In summary, just because you are bad at something or don't fully understand it, does not make that thing worthless.
Structured comments make it easier to automatically extract information from comments; it does not make it easier to add information.
Comments are so limited, you cannot put meaningful documentation inside them, and by enforcing a rigid structure you are encouraging poor documentation, and making it impossible to write good documentation.
Generally speaking, I find that if a function parameter isn't apparent from the code or its name (prototype, minidoc, etc), then the API is probably stupid and was written by an idiot. I have never seen those situations saved by documentation.
>>83
It's very possible to add that ``meaningful'' information without adding the clutter XML does. This isn't mainly about structured comments (though >>85 is right about those), it's specifically about using XML to do it.
As far as attempts at literate programming go, XML is a failure because it makes the source code messier and harder to read.
Visual Studio makes the XML trivial as it adds it for you, you only need to provide the content.
Comments are only limited by a persons ability to accurately describe the code. Its apparent that you have not used a mature API extensively. Take something like the .Net APIs. The Visual Studio object explorer displays the XML comments for the APIs (and any other well commented code you are using). This tool is invaluable as is intelligence which also gets its info from the XML comments.
Parameter names should be self evident, but they can't always be. If a function takes a path to a file name, and it has to be a fully qualified path do you name it "strPathName"? That doesn't tell you shit about it. Its obviously for a path, but is it a relative path or a fully qualified one or doesn't it matter? What if there are overloads that take other paths, do you have to get super descriptive? Do you name it "strFullyQualifiedPathNameToTheFileYouWantToWorkWith"? Or maybe I should just memorize the API's full documentation, that sure is reasonable.
Or would it work better if you name it "PathName" and a little tool-tip came up when you got to the point to enter the parameter in the IDE and it read "String: Fully qualified path to the file to work with." Think about that for a while.
/// <summary>
/// Summary of LoadXMLFromFile.
/// </summary>
/// <param name="FilePath">Description of FilePath parameter.</param>
public void LoadXMLFromFile(string FilePath)
That is a basic C# XML comment (that is autogenerated with me adding the text between the tags). If you find that hard to read or pushing the comment delimited 3 times to auto-gen the XML to hard to do, you might want to choose a different hobby.
Any good developer today should be able to view XML and understand it. But since you don't, I suppose you have a better idea for a markup language to use to give context and meaning to programming comments. You can't be a true badass programmer until you have dismissed, without a reason, the ideas that teams of computer scientists and computer engineers have put way more thought in to that you have.
> Visual Studio makes the XML trivial as it adds it for you, you only need to provide the content.
I didn't disagree with that. I said the hard part is adding the content- something that automatic documentation has made harder by removing incentive, not easier.
> Parameter names should be self evident, but they can't always be.
Prove it, cock for brains.
> If a function takes a path to a file name, and it has to be a fully qualified path do you name it "strPathName"?
Straw man. Don't make an API that requires a fully qualified path, duh.
I'm still waiting... Maybe you can try an argument that doesn't depend on such a weak strawman next time.
Wow, I am seriously seeing a pattern develop here. You really have a hard time understanding these simple concepts.
>something that automatic documentation has made harder by removing incentive, not easier
Yes, automating a task will remove incentive to do that task. Brilliant! And this whole time automation is used as incentive to do some task, but you have turned that whole idea on its head with your brilliance.
>Prove it, cock for brains.
Did, you didn't understand.
You claim straw man argument, but fail to even prove you used the correct word there. I chose a simple example that you see in many APIs on many platforms. So what I said was not a fallacy (hence no straw man claims to be made).
>Don't make an API that requires a fully qualified path, duh.
Depending on the scope of an API that is not always reasonable. And given that there is no standard, one can't know what they should expect by default.
How is one supposed to know if the argument is a fully qualified path, or a relative path to some other directory? If it is relative, from what directory are we starting? This is all answered in documentation, not paramnames. And if that documentation has some way of identifying that a certain piece of it refers to the pa ram in question, it can be more effectively utilized by tools (most notably IDE in this case) and be of greater use to the developer. Since creating the markup to make the documentation more useful is automated, it is no extra work for the developer to utilize.
I can't be more clear and I totally expect you to not understand that at all.
It is obvious you don't program enough of create sophisticated enough programs.
> Yes, automating a task will remove incentive to do that task.
So you agree that autodocumentation decreases the quality of good literate documentation, you simply disagree when I say bad autodocumentation is worse than no documentation?
> Depending on the scope of an API that is not always reasonable.
Wrong. Making a good and solid API is always reasonable, and sacrificing code quality and robustness causes other problems that your precious autodocumentation cannot fix.
> How is one supposed to know if the argument is a fully qualified path, or a relative path to some other directory?
That's insane. How does POSIX.1 open() know? How does Common-Lisp's make-pathname know? How does Boost.Filesystem know?
Pick a different example besides relative paths. This is a solved problem; a strawman at best, and a demonstration that your whole argument is without merit at worst.
> I can't be more clear and I totally expect you to not understand that at all.
Of course you do! You think "How could anyone hate those little yellow tooltips that say 'absolute path required'" and you know that those little yellow tooltips are what make you productive enough to handle tasks you could never handle before.
Grow up and re-read what I've been saying here. I am saying I would trade those little yellow tooltips for good documentation or a good api.
> It is obvious you don't program enough of create sophisticated enough programs.
Seriously. People wrote "sophisticated programs" before xml, syntax hilighting and Visual Studio. How naive are you to think that others don't need the crutches that you do?