Tool used to generate cplusplus documentation
Pages: 12
What tool is used to generate the reference documentation for this site? Is it available for use on my project?
There is a tool to generate documentation, it's called Doxygen.
http://www.stack.nl/~dimitri/doxygen/
( AFAIK Documentation on this website has not been automatically generated )
http://www.stack.nl/~dimitri/doxygen/
( AFAIK Documentation on this website has not been automatically generated )
Actually Java has the Javadoc feature built-in as long as we developers document our class methods etc and running a tool provided it auto-generate the documentation.
I wonder if C++ committee would like to in-corporate such feature as part of Standard C++ ? I admit it is a good to have feature but you can say make it as Standard C++ but it is optional whether developers want to use it just like what Java does.
I wonder if C++ committee would like to in-corporate such feature as part of Standard C++ ? I admit it is a good to have feature but you can say make it as Standard C++ but it is optional whether developers want to use it just like what Java does.
closed account (3hM2Nwbp)
A standardized documentation tool for C++ would be the single most important improvement to the language IMHO. Among most of the languages I've used, C and C++ libraries have always seemed to have the hardest to decipher documentation. There are many libraries that I simply refuse to use because of how poorly documented they are1
1 I do not consider browsing source code to be an acceptable means of documentation.
1 I do not consider browsing source code to be an acceptable means of documentation.
Last edited on
That would be nice, but given how long we've been waiting for C++0x, there are probably more important matters to be attended to. Moreover, if we include things like that, everything will start getting bloated. As far as I can see, doxgen is the most standard for native C++, and maybe Sandcastle for .NET?
closed account (3hM2Nwbp)
Doxygen is a gem - it's a pity so many people don't use it.
* Does anyone know if there's a java-doc like resource for the standard C++ library (Including what throws? Preconditions? Postconditions?) As good as this site's reference is, there still exists ambiguity in places....
* Does anyone know if there's a java-doc like resource for the standard C++ library (Including what throws? Preconditions? Postconditions?) As good as this site's reference is, there still exists ambiguity in places....
Last edited on
You can also try Microsoft's MSDN documentation. I think it exists for the C++ standard library, just watch out for "Microsoft Specific" pages (they do mark pages as such where necessary).
GNU libstdc++ has doxygen documentation. |
What we are asking is for the Standard C++ committee members to endorse say Doxygen as the official standard documentation for C++. But from what I know, C++ committee members are taking ages to standardize stuff. I feel they are out of touch with the reality. IT moves fast and so does language features. By the time they agree and standardize on some features, those maybe obsolete by then technologies. It is like always playing catch-up instead of staying at the front and remain relevant.
| What we are asking is for the Standard C++ committee members to endorse say Doxygen as the official standard documentation for C++. But from what I know, C++ committee members are taking ages to standardize stuff. I feel they are out of touch with the reality. IT moves fast and so does language features. By the time they agree and standardize on some features, those maybe obsolete by then technologies. It is like always playing catch-up instead of staying at the front and remain relevant. |
Sure, the working group takes a long time, but its members have day jobs in addition to working on the C++ standard, spending time with family, etc. Designing a language as complex, yet powerful, as C++ while addressing all of the pitfalls of its parent language C is a fair bit of work in itself anyway. For example, adding support for threads in C++0x when C can't provide any guidance due to its need for maximum portability is a lot of work. Making sure to address and/or handle pointers and non-POD types (classes) in new template classes such as std::tuple<> is a lot of work too. It may take a long time, but that's only because so much thought goes into the process and because of the lack of time in a day.
Hi chronokitsune, you seem to fall under the camp where you advocate for complete-ness and thorough-ness before releasing something to the public as those API will then be cast in stone and hard to change without breaking any existing interfacing programs. That reason is valid.
However, looking at how fast IT moves, a separate alternative should be sought after isn't it? The final release maybe full of quirks or minor faults but as long as those new major features do not suffer and it works in general, then it is ok to go ahead. Look at Perl releases. Perl maybe full of quirks and faults but in general it works so it is ok to use it. Look at Java again. It is also same.
Now looking at how Perl, Java progresses with new releases and looking at how C++ is moving, I fall under the camp of Perl,Java. I prefer quicker releases (with minor quirks and faults which is acceptable to me).
No camps are wrong in their approach. It just happen that I fall under the "faster release" camp :)
However, looking at how fast IT moves, a separate alternative should be sought after isn't it? The final release maybe full of quirks or minor faults but as long as those new major features do not suffer and it works in general, then it is ok to go ahead. Look at Perl releases. Perl maybe full of quirks and faults but in general it works so it is ok to use it. Look at Java again. It is also same.
Now looking at how Perl, Java progresses with new releases and looking at how C++ is moving, I fall under the camp of Perl,Java. I prefer quicker releases (with minor quirks and faults which is acceptable to me).
No camps are wrong in their approach. It just happen that I fall under the "faster release" camp :)
A C++ program spends more time in development and has to go through much more testing than a Java or Perl program of similar complexity. It doesn't make sense to release a new version of a language every year when most of your user base is made up of extremely complex programs where a small change would imply a whole battery of tests.
Also, C++ is often used to implement the infrastructure of larger systems. The possibility of bugs due to linguistic quirks or subtly-altered semantics seems like a high price to pay just so the latest fad can be available more quickly in the standard definition. Not to mention that a standard feature only makes sense as long as there's at least a few compilers or standard libraries that implement it. It's pointless to add features to the language faster than they can be implemented. Remember that it took a few years for GCC to implement a significant portion of C++98. Then there's the controversial export keyword.
Also, C++ is often used to implement the infrastructure of larger systems. The possibility of bugs due to linguistic quirks or subtly-altered semantics seems like a high price to pay just so the latest fad can be available more quickly in the standard definition. Not to mention that a standard feature only makes sense as long as there's at least a few compilers or standard libraries that implement it. It's pointless to add features to the language faster than they can be implemented. Remember that it took a few years for GCC to implement a significant portion of C++98. Then there's the controversial export keyword.
Also, C++ is often used to implement the infrastructure of larger systems. The possibility of bugs due to linguistic quirks or subtly-altered semantics seems like a high price to pay just so the latest fad can be available more quickly in the standard definition |
I think the above comments sum it all. Since infrastructure are very important component for large systems then the more though-out process is justified for C++.
That also explains why most business-centric applications are built in Java,Perl,PHP,Javascript etc. So if developers want to focus on business-centric applications, than they would be better off developing in Java,Perl etc instead isn't it ?
This creates a "sphere" where C++ developers are holed up inside doing infrastructure development. Please note I am not bashing C++, in fact I wanted C++ to enjoy mainstream success like other Java,Perl languages do but albeit it is just wishful thinking on my part.
Fast releases don't generally happen with ISO standards, especially something as large and complex as C++. With Java, a single entity controls the standard: Oracle (and Sun before that). The same is true of a number of other languages such as the JavaScript scripting language (no relation to the Java programming language), which is standardised by the Mozilla Corporation, and the D programming language, which is maintained by a company named Digital Mars.
If someone wants C++ to move faster, that person might learn how to add his/her own compiler extensions to an open-source compiler like the GNU or Clang C++ compilers. Compiler extensions can be made standard in future versions of the C++ standard. Another possibility is creating a library of "Useful ThingsTM". After all, Boost is quite well known, and some of its concepts were at least considered for inclusion in C++0x; some of them even made it into the final draft submitted to ISO, so that's a bit of hope if someone chose to go that route. :)
The point is that, like IT, compilers and their various extensions can move quickly, even if the C++ standard itself doesn't.
If someone wants C++ to move faster, that person might learn how to add his/her own compiler extensions to an open-source compiler like the GNU or Clang C++ compilers. Compiler extensions can be made standard in future versions of the C++ standard. Another possibility is creating a library of "Useful ThingsTM". After all, Boost is quite well known, and some of its concepts were at least considered for inclusion in C++0x; some of them even made it into the final draft submitted to ISO, so that's a bit of hope if someone chose to go that route. :)
The point is that, like IT, compilers and their various extensions can move quickly, even if the C++ standard itself doesn't.
| I wanted C++ to enjoy mainstream success like other Java,Perl languages do |
You're ten years late. This was the situation during the mid-1990s. Right now Java is in the exact same place C++ was back then. |
That is what I meant by IT move fast and very fast indeed. Right now developers dabble in .NET and in general leaning towards mobile development which either by coincidence using Java, .NET or Apple proprietary language.
The idea is since IT move fast, developers usually hope the standards move fast too but it seems the contrary. Implementation drive the standards rather than the other way round :)
You're ten years late. This was the situation during the mid-1990s. Right now Java is in the exact same place C++ was back then. |
Yes, C++ was used once upon a time for business programming (until ~1998, when Java took it over). The only difference is there is no such threat to Java now, as Java was to C++ back then.
With Java, a single entity controls the standard: Oracle |
No, the standard is controlled by the JCP committee members who vote for or against JSRs anyone can submit. The list is here: http://jcp.org/ja/participation/members/
As you can see, not only Oracle is there, but Google, RedHat, Apple and others are there too.
Since infrastructure are very important component for large systems then the more though-out process is justified for C++. |
This is a poor excuse of slow movement of C++, because Java is probably even more common for infrastructure software than C++ is. Many big companies run their big databases implemented almost exclusively in Java. The JVMs are written usually in C++, but, who cares?
Properly managed frequent releases decrease the risk of bugs. It is not "test less" to release faster, it is "change less".
Anyway, back to the topic: there is that Doxygen, right? But why its HTML output looks like it was created by your Grandma using MS FrontPage in the mid 1990s? Hello, this is 2011, we have JS, CSS3 and HTML5 (almost)? See ScalaDoc how good documentation should look like.
Last edited on
When I said "infrastructure", I was talking about things like database engines and other things at the lowest level.
The great thing about open source is that you can fix the things you don't like.
That being said, what kind of a fag cares what the documentation looks like?
| there is that Doxygen, right? But why its HTML output looks like it was created by your Grandma using MS FrontPage in the mid 1990s? Hello, this is 2011, we have JS, CSS3 and HTML5 (almost)? See ScalaDoc how good documentation should look like. |
That being said, what kind of a fag cares what the documentation looks like?
Ahahahahahaha :))) Can I cite that last part when reporting to my boss? (just joking, my boss probably doesn't even know that C++ is a name of a programming language).
On another note: Doxygen is used by the most advanced mathematics programming project in my field (called the LiE package). LiE is written in C, rather than C++ however.
[Edit: warning: intentional teaser ahead don't take seriously]
http://www.infoworld.com/d/application-development/oracle-javas-worst-enemy-168828
On another note: Doxygen is used by the most advanced mathematics programming project in my field (called the LiE package). LiE is written in C, rather than C++ however.
[Edit: warning: intentional teaser ahead don't take seriously]
http://www.infoworld.com/d/application-development/oracle-javas-worst-enemy-168828
Last edited on
Pages: 12