[Boost-users] [Serialization] Use of BOOST_SERIALIZATION_NVP needs clarification

From: Peter Whaite (boost_at_[hidden])
Date: 2005-12-01 14:21:10

I just started using the serialization library and it is very useful.
However the minimal documentation for xml archives in the "List of
Examples" could be clearer.  Right now it says...

demo_xml.cpp
    This is a variation the original demo which supports xml archives in
    addition to the others. The extra wrapping macros are needed to
    associate a data item name with the correspoding xml tag. For more
    information see Name-Value Pairs. Here is what an xml archive looks
    like.

It would help if the "extra wrapping macros" are named.  Yes you can
figure it out from demo_xml.cpp (well there's only
BOOST_SERIALIZATION_NVP in there) and from the "Name-Value Pairs" page,
but that is too much jumping around for a first read.

But what would help more is a warning that BOOST_SERIALIZATION_NVP must
wrap a valid xml tag.  For example I naively thought:

    void editor::save() {
        ...
        ar << BOOST_SERIALIZATION_NVP(*this);
    }

would work, but of course it doesnt because "*this" is not a valid xml
tag.  I searched the list archives, and I'm not the only one who fell
into this trap.  I suggest adding something like this

     ... The extra wrapping macro, BOOST_SERIALIZATION_NVP(name), is
     needed to associate a data item name with the corresponding xml
     tag.  It is importanted that 'name' be a valid xml tag, else it
     will be impossible to restore the archive.  For more information...

The warning should be repeated in wrappers.html#nvp, and in the comments
in demo_xml.cpp. 

---
Peter Whaite