Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
On Jun 23, 2008, at 9:31 PM, Martin Sebor wrote: Travis Vitek wrote: Martin Sebor wrote: [...] I gave a number of arguments against Doxygen comments in stdcxx headers: 1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished product Since we aren't providing any html documentation for any c++0x code at this time, maybe we should stop using html documentation? :P So the options are-- a) not document the c++0x code at all b) write up documentation for all new code in html to be consistent with what is used currently c) move all existing documentation over to doxygen before a single doxygen comment is added to the new code Assuming we want to have C++ 0x fully documented in 5.0 or shortly thereafter which of (b) and (c) do you think is viable? I don't think any of those choice are viable _in the near term_ but if I had to choose? C. If only to get a better idea of how much work we're really talking about. But I don't think doing that right now is really necessary. I think we all agree, there's too much C++0x work to be done in the near term that virtually prohibits migrating the old HTML docs right now. But that doesn't mean we should not be writing new documentation. ... I know that at Rogue Wave we have an xslt that transforms from doxygen generated xml files to html documentation, so unless using doxygen is totally ruled out, that can be used to bridge between the old html pages and generated ones. Yes, but the transformation isn't fully automated and according to Marc requires quite a bit of human intervention. It's clear that we don't have the bandwidth to take this on and still make our target date. I agree... to a degree. We don't have the bandwidth at present but it is not at all clear (to me at least) how much work this migration will really require. ... For starters, what prevents me from browsing all new Doxygen docs is that there is no generated HTML documentation. I and everyone else would have to install Doxygen and compile the HTML docs ourselves to get the benefit. I don't think there's anything that prevents us from copying and redistributing our own documentation. You only need Doxygen installed if you need to regenerate the docs for some reason. And because the docs aren't being generated and the generated HTML looked they're likely to contain all kinds of formatting problems. I've generated them. And yes, there are formatting problems. ... Doxygen doesn't have to document everything that it sees. There are many ways to control what will be documented. You can tell it to only generate documentation for things that have doxygen style comments or you can mark things as internal so the documentation can be conditionally disabled. I've seen the libstdc++ documentation (see below) and talked to the project's maintainers. My understanding is that they're not completely happy with it for some of the same reasons I've raised here and are considering (or maybe even working on) migrating away from Doxygen to some other tool/format. A better tool/format than Doxygen? Wow. I'd be interested in reading that thread of discussion! Link? BTW, I'm still trying to figure out what it is that you are proposing exactly. :D Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Eric Lemings wrote: On Jun 23, 2008, at 9:31 PM, Martin Sebor wrote: Travis Vitek wrote: Martin Sebor wrote: [...] I gave a number of arguments against Doxygen comments in stdcxx headers: 1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished product Since we aren't providing any html documentation for any c++0x code at this time, maybe we should stop using html documentation? :P So the options are-- a) not document the c++0x code at all b) write up documentation for all new code in html to be consistent with what is used currently c) move all existing documentation over to doxygen before a single doxygen comment is added to the new code Assuming we want to have C++ 0x fully documented in 5.0 or shortly thereafter which of (b) and (c) do you think is viable? I don't think any of those choice are viable _in the near term_ but if I had to choose? C. If only to get a better idea of how much work we're really talking about. [...] BTW, I'm still trying to figure out what it is that you are proposing exactly. :D We have an established (albeit undocumented) process and infrastructure for documenting code and publishing the documentation. The onus is on you and Travis to come up with a proposal if you want to change how things are done. So far you've decided on your own, despite my objections and without establishing consensus, to start adding Doxygen style comments to new headers, without reconciling the differences between the existing process and your new one, and without providing a clear path to such a reconciliation in the foreseeable future. Unless these issues are satisfactorily resolved and until there is a viable plan for producing a adequate replacement for the existing class reference on a reasonable schedule I have to insist that the Doxygen comments be removed from the newly added headers. Martin
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
-Original Message- From: Martin Sebor [mailto:[EMAIL PROTECTED] Sent: Tuesday, June 24, 2008 6:55 AM To: dev@stdcxx.apache.org Subject: Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Eric Lemings wrote: ... BTW, I'm still trying to figure out what it is that you are proposing exactly. :D We have an established (albeit undocumented) process and infrastructure for documenting code and publishing the documentation. The onus is on you and Travis to come up with a proposal if you want to change how things are done. I thought I did. To repeat...for the record, write new documentation using Doxygen comments now. Migrate the old HTML docs later. So far you've decided on your own, despite my objections and without establishing consensus, to start adding Doxygen style comments to new headers, without reconciling the differences between the existing process and your new one, and without providing a clear path to such a reconciliation in the foreseeable future. Hmm. Let me see if I can summarize your objections: 1. You don't like Doxygen. I think that's pretty evident. :) Nothing wrong with that. I think it's the best damn doc tool on the market...but that's just me. But if you know of a better tool and/or format, we're all ears. 2. We shouldn't write any documentation comments because it's not conventional. Convention isn't really the right: this is becoming more like dogma. Travis and I both realize what this means -- breaking with this convention -- moving forward. It's not easy writing docs and code at the same time, and the new code will look different from the older code (for a period of time at least), but it is the right thing to do we believe. Unless these issues are satisfactorily resolved and until there is a viable plan for producing a adequate replacement for the existing class reference on a reasonable schedule I have to insist that the Doxygen comments be removed from the newly added headers. And then what? Hope that the documentation magically appears? I'd be glad to remove it...if you have a better plan, solution, proposal... something in mind. But just removing the documentation comments is not a clear path to such reconciliation in the foreseeable future either. It's the absolute last thing we should be contemplating in fact. Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Eric Lemings wrote: -Original Message- From: Martin Sebor [mailto:[EMAIL PROTECTED] Sent: Tuesday, June 24, 2008 6:55 AM To: dev@stdcxx.apache.org Subject: Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Eric Lemings wrote: ... BTW, I'm still trying to figure out what it is that you are proposing exactly. :D We have an established (albeit undocumented) process and infrastructure for documenting code and publishing the documentation. The onus is on you and Travis to come up with a proposal if you want to change how things are done. I thought I did. To repeat...for the record, write new documentation using Doxygen comments now. Migrate the old HTML docs later. Sorry. One sentence doesn't make a proposal, certainly not one this vague. So far you've decided on your own, despite my objections and without establishing consensus, to start adding Doxygen style comments to new headers, without reconciling the differences between the existing process and your new one, and without providing a clear path to such a reconciliation in the foreseeable future. Hmm. Let me see if I can summarize your objections: 1. You don't like Doxygen. I think that's pretty evident. :) Not at all. You completely misinterpreted what I said. Nothing wrong with that. I think it's the best damn doc tool on the market...but that's just me. But if you know of a better tool and/or format, we're all ears. 2. We shouldn't write any documentation comments because it's not conventional. Nope. Again, you're missing my point. I'm saying changes to process should be made only with a solid plan in place and with consensus. Convention isn't really the right: this is becoming more like dogma. Travis and I both realize what this means -- breaking with this convention -- moving forward. It's not easy writing docs and code at the same time, and the new code will look different from the older code (for a period of time at least), but it is the right thing to do we believe. I disagree. Unless these issues are satisfactorily resolved and until there is a viable plan for producing a adequate replacement for the existing class reference on a reasonable schedule I have to insist that the Doxygen comments be removed from the newly added headers. And then what? Hope that the documentation magically appears? I'd be glad to remove it...if you have a better plan, solution, proposal... something in mind. The current process is to maintain the existing docs in HTML, using the existing infrastructure to publish the docs on the site. You want to change it? Fine. Propose in detail how and when this will change will take place and when we can expect it to be done. But just removing the documentation comments is not a clear path to such reconciliation in the foreseeable future either. It's the absolute last thing we should be contemplating in fact.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Eric Lemings wrote: Gah. I have to update my docs as well: template parameters are documented using the @tparam tag rather than the @param tag. I thought we said we wouldn't be using doxygen comments in library code. Am I misremembering? Martin http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam Brad. -Original Message- From: Travis Vitek Sent: Monday, June 16, 2008 11:47 AM To: Eric Lemings Subject: RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Damn, now I have to update my dox. -Original Message- From: Eric Lemings Sent: Monday, June 16, 2008 10:44 AM To: Travis Vitek Subject: RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h -Original Message- From: Travis Vitek Sent: Monday, June 16, 2008 10:21 AM To: Eric Lemings Subject: RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Author: elemings Date: Fri Jun 13 13:16:06 2008 New Revision: 667636 +/** + * An identity wrapper. Similar to the identity property, the identity + * wrapper is a class template that simply reflects the type of its + * template parameter. This class template is used when a template + * parameter type must be explicitly specified in order to apply the + * correct move/forwarding semantics, usually in the \c std::forward() + * function. + * + * @param _Type Any type. No restrictions or requirements. + * @see std::forward + */ +template class _Type +struct identity Does doxygen handle @param when we are talking about a template parameter? Not yet. http://www.mail-archive.com/[EMAIL PROTECTED] /msg163022.html
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Martin Sebor wrote: Eric Lemings wrote: Gah. I have to update my docs as well: template parameters are documented using the @tparam tag rather than the @param tag. I thought we said we wouldn't be using doxygen comments in library code. Am I misremembering? I know that it was requested that I remove the doxygen comments from the type traits stuff I have been working on, but I decided it would be best to commit them with the comments intact and remove them only if necessary. I mentioned this to Brad in our off-list correspondence, and he has opted to do the same. As I sit here thinking about it, I can't remember exactly why it was decided that they should be removed. Perhaps it is best to have this discussion again, but on the list this time. To start, I'm not sure I understand the motivation for _not_ using doxygen in the library headers. I realize that having documentation in the code is a departure from what stdcxx has done in the past, but I'm not convinced that this is a bad thing. Travis Martin http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Eric Lemings wrote: -Original Message- From: Travis Vitek [mailto:[EMAIL PROTECTED] Sent: Monday, June 23, 2008 10:13 AM To: dev@stdcxx.apache.org Subject: RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Martin Sebor wrote: Eric Lemings wrote: Gah. I have to update my docs as well: template parameters are documented using the @tparam tag rather than the @param tag. I thought we said we wouldn't be using doxygen comments in library code. Am I misremembering? I know that it was requested that I remove the doxygen comments from the type traits stuff I have been working on, but I decided it would be best to commit them with the comments intact and remove them only if necessary. I mentioned this to Brad in our off-list correspondence, and he has opted to do the same. As I sit here thinking about it, I can't remember exactly why it was decided that they should be removed. Perhaps it is best to have this discussion again, but on the list this time. To start, I'm not sure I understand the motivation for _not_ using doxygen in the library headers. I realize that having documentation in the code is a departure from what stdcxx has done in the past, but I'm not convinced that this is a bad thing. I'll add a couple points to that for the record. Much of this was precipitated when I noticed that GNU libstdc++ also includes their documentation right in the library headers and source code. Why? Because most, if not all, C/C++ preprocessors will strip comments by default during a first pass. Thus, the impact of extensive documentation comments on overall build times is negligible. Of course preprocessors strip comments. It's required by the language standards. But regardless of the translation stage at which the stripping takes place, it isn't without cost. I gave a number of arguments against Doxygen comments in stdcxx headers: 1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished product 2) Doxygen markups are harder to read than ordinary comments (see 3), and in the library headers the volume of such comments will, in many cases, dwarf the amount of code 3) unless/until there is infrastructure to generate the HTML docs from the Doxygen comments documenting the library (or other parts of stdcxx) using Doxygen markups serves no purpose 4) the HTML generated from stdcxx headers is unavoidably ugly because of the necessity to uglify names (leading underscores, etc.) Martin
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Martin Sebor wrote: Eric Lemings wrote: Travis Vitek wrote: Martin Sebor wrote: I thought we said we wouldn't be using doxygen comments in library code. Am I misremembering? I know that it was requested that I remove the doxygen comments from the type traits stuff I have been working on, but I decided it would be best to commit them with the comments intact and remove them only if necessary. I mentioned this to Brad in our off-list correspondence, and he has opted to do the same. As I sit here thinking about it, I can't remember exactly why it was decided that they should be removed. Perhaps it is best to have this discussion again, but on the list this time. To start, I'm not sure I understand the motivation for _not_ using doxygen in the library headers. I realize that having documentation in the code is a departure from what stdcxx has done in the past, but I'm not convinced that this is a bad thing. I'll add a couple points to that for the record. Much of this was precipitated when I noticed that GNU libstdc++ also includes their documentation right in the library headers and source code. Why? Because most, if not all, C/C++ preprocessors will strip comments by default during a first pass. Thus, the impact of extensive documentation comments on overall build times is negligible. Of course preprocessors strip comments. It's required by the language standards. But regardless of the translation stage at which the stripping takes place, it isn't without cost. I gave a number of arguments against Doxygen comments in stdcxx headers: 1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished product Since we aren't providing any html documentation for any c++0x code at this time, maybe we should stop using html documentation? :P So the options are-- a) not document the c++0x code at all b) write up documentation for all new code in html to be consistent with what is used currently c) move all existing documentation over to doxygen before a single doxygen comment is added to the new code Another important point is that the stdcxx project doesn't have anyone volunteering time to write documentation. If we want the documentation, we're likely going to have to do it ourselves, and I find using doxygen comments _much_ simpler than writing html. I know that at Rogue Wave we have an xslt that transforms from doxygen generated xml files to html documentation, so unless using doxygen is totally ruled out, that can be used to bridge between the old html pages and generated ones. 2) Doxygen markups are harder to read than ordinary comments (see 3), and in the library headers the volume of such comments will, in many cases, dwarf the amount of code If the code is well written, comments are usually reserved for situations where they are necessary to describe what the code is actually supposed to be doing. Most frequently this type of comment would be found in the body of a function definition. Doxygen comments, on the other hand, usually appear with the declarations, so the type of comments that you would usually need to read aren't necessarily in the same place as the doxygen comments. Additionally, your editor can likely be configured to hide the doxygen comments if you don't want to see them. As for readability, consider this. There are currently no comments describing what a given library class or function is expected to do. If you want to see what the expected behavior is, you get to walk yourself through the implementation, or you get to fire up a web browser and look at the html documentation. If the documentation is added as doxygen comments, they are in the code. They may be slightly less readable than plain english text due to the additional markup, but there is _nothing_ that is stopping you from looking to the implementation or firing up a web browser like you did before. 3) unless/until there is infrastructure to generate the HTML docs from the Doxygen comments documenting the library (or other parts of stdcxx) using Doxygen markups serves no purpose Which would you like first, the chick or the egg? The infrastructure will never be built to generate html documentation from doxygen comments if we don't have doxygen comments to generate documentation from. 4) the HTML generated from stdcxx headers is unavoidably ugly because of the necessity to uglify names (leading underscores, etc.) I thought leading underscores made code run faster. :) Doxygen doesn't have to document everything that it sees. There are many ways to control what will be documented. You can tell it to only generate documentation for things that have doxygen style comments
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
-Original Message- From: Martin Sebor [mailto:[EMAIL PROTECTED] Sent: Monday, June 23, 2008 11:38 AM To: dev@stdcxx.apache.org Subject: Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Eric Lemings wrote: -Original Message- From: Travis Vitek [mailto:[EMAIL PROTECTED] Sent: Monday, June 23, 2008 10:13 AM To: dev@stdcxx.apache.org Subject: RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h Martin Sebor wrote: Eric Lemings wrote: Gah. I have to update my docs as well: template parameters are documented using the @tparam tag rather than the @param tag. I thought we said we wouldn't be using doxygen comments in library code. Am I misremembering? I know that it was requested that I remove the doxygen comments from the type traits stuff I have been working on, but I decided it would be best to commit them with the comments intact and remove them only if necessary. I mentioned this to Brad in our off-list correspondence, and he has opted to do the same. As I sit here thinking about it, I can't remember exactly why it was decided that they should be removed. Perhaps it is best to have this discussion again, but on the list this time. To start, I'm not sure I understand the motivation for _not_ using doxygen in the library headers. I realize that having documentation in the code is a departure from what stdcxx has done in the past, but I'm not convinced that this is a bad thing. I'll add a couple points to that for the record. Much of this was precipitated when I noticed that GNU libstdc++ also includes their documentation right in the library headers and source code. Why? Because most, if not all, C/C++ preprocessors will strip comments by default during a first pass. Thus, the impact of extensive documentation comments on overall build times is negligible. Of course preprocessors strip comments. It's required by the language standards. But regardless of the translation stage at which the stripping takes place, it isn't without cost. I gave a number of arguments against Doxygen comments in stdcxx headers: 1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished product What Travis said: if we don't write it ourselves, it probably won't get written. :) I also agree: I'd rather write doc comments than update the existing raw HTML docs. 2) Doxygen markups are harder to read than ordinary comments (see 3), and in the library headers the volume of such comments will, in many cases, dwarf the amount of code That's subjective. Because they are more structured than free-form comments, I find them easier to read. 3) unless/until there is infrastructure to generate the HTML docs from the Doxygen comments documenting the library (or other parts of stdcxx) using Doxygen markups serves no purpose I consider that icing on the cake. You can still generate docs without having them published online. 4) the HTML generated from stdcxx headers is unavoidably ugly because of the necessity to uglify names (leading underscores, etc.) This can be controlled with conditional sections and comments, using @if tags, @internal tags, _RWSTD_EXT_DOXYGEN macro, and other such mechanisms. Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
[EMAIL PROTECTED] wrote:
Author: elemings
Date: Fri Jun 13 13:16:06 2008
New Revision: 667636
URL: http://svn.apache.org/viewvc?rev=667636view=rev
Log:
2008-06-13 Eric Lemings [EMAIL PROTECTED]
STDCXX-958
* include/rw/_forward.h: New header file containing initial
implementation of std::identity class template; std::forward()
and std::move() functions; and internal _RWSTD_MOVE() macro.
Added:
stdcxx/branches/4.3.x/include/rw/_forward.h
Added: stdcxx/branches/4.3.x/include/rw/_forward.h
URL:
http://svn.apache.org/viewvc/stdcxx/branches/4.3.x/include/rw/_forward.h?rev=667636view=auto
==
--- stdcxx/branches/4.3.x/include/rw/_forward.h (added)
+++ stdcxx/branches/4.3.x/include/rw/_forward.h Fri Jun 13 13:16:06 2008
[...]
+template class _Type
Please follow the current naming convention for the names
of template parameters.
+struct identity
+{
+/** Identifies template parameter type. */
+typedef _Type type;
+
+/**
+ * Conversion operator. This operator converts the parameter value
+ * to the wrapped identity type.
+ *
+ * @param __x An value convertible to identity type.
+ * @returns Same value as the function argument with identity type.
+ */
+const _Type operator() (const _Type __x) {
The member function is supposed to be const.
+return __x;
+}
+};
+
+
+#if !defined _RWSTD_NO_RVALUE_REFERENCES
+
+/**
+ * Forwards appropriate rvalue or lvalue reference type. This function
+ * is used to ensure that the appropriate reference type is used in move
+ * semantics.
+ *
+ * @param _Type An lvalue or rvalue reference type.
+ * @param __x An lvalue reference or rvalue reference.
+ * @returns An lvalue if __x is an lvalue reference; otherwise, an rvalue.
+ */
+_EXPORT
Only out-of-line templates need to be declared exported.
Out-of-line function templates must be defined in .cc
files, and .cc files containing exported definitions
need to be explicitly #included in export.cpp.
This function template as well as move() below should be
declared inline.
+template class _Type
+_Type
+forward (_TYPENAME identity_Type::type __x)
+{
+return __x;
+}
+
+/**
+ * Move a value to an rvalue reference. This function is used to
+ * explicitly bind constructors and other functions with rvalue
+ * references that employ move semantics.
+ *
+ * @param __x An lvalue or rvalue.
+ * @returns Same value as parameter with rvalue reference type.
+ */
+_EXPORT
+template class _Type
+_TYPENAME _RW::__rw_remove_reference_Type::type
+move (_Type __x)
+{
+return __x;
+}
+
+/**
+ * @internal
+ * Internal wrapper macro to utilize move semantics if available.
+ * @param __x An lvalue or rvalue.
+ */
+# define _RWSTD_MOVE(__x) std::move (__x)
^
This should be _STD::move (__x).
Thanks!
Martin
+#else // no rvalue references
+# define _RWSTD_MOVE(__x) (__x)
+
+#endif // !defined _RWSTD_NO_RVALUE_REFERENCES
+
+
+} // namespace std
+
+
+# endif // !defined _RWSTD_NO_EXT_CXX_0X
+
+#endif // _RWSTD_RW_FORWARD_INCLUDED
