[ADT] Annotate immutable data structure methods with LLVM_NODISCARD.

[NoQ]

Summary

This would warn the developer on the very common bug that consists in writing, eg., Factory.add(Set, Item); instead of Set = Factory.add(Set, Item);. Because in the first snippet the updated Set object is discarded while the original object remains unchanged (because it's, well, immutable), which isn't what you ever want to do.

LLVM_NODISCARD is essentially warn_unused_result.

For now no such bugs were found in llvm or clang (in fact, these data structures are mostly used by the clang static analyzer), but i made these mistakes myself knowingly and i see many such bugs during code review.

Adding @chandlerc because he's the code owner for ADT and analyzer folks because it's mostly about the analyzer.

llvm/trunk/include/llvm/ADT/ImmutableList.h

public:
 
   ImmutableListFactory(BumpPtrAllocator& Alloc)
   : Allocator(reinterpret_cast<uintptr_t>(&Alloc) | 0x1) {}
 
   ~ImmutableListFactory() {
     if (ownsAllocator()) delete &getAllocator();
   }
 
-  ImmutableList<T> concat(const T& Head, ImmutableList<T> Tail) {
+  LLVM_NODISCARD ImmutableList<T> concat(const T &Head, ImmutableList<T> Tail) {
     // Profile the new list to see if it already exists in our cache.
     FoldingSetNodeID ID;
     void* InsertPos;
 
     const ListTy* TailImpl = Tail.getInternalPointer();
     ListTy::Profile(ID, Head, TailImpl);
     ListTy* L = Cache.FindNodeOrInsertPos(ID, InsertPos);
 
     if (!L) {
       // The list does not exist in our cache.  Create it.
       BumpPtrAllocator& A = getAllocator();
       L = (ListTy*) A.Allocate<ListTy>();
       new (L) ListTy(Head, TailImpl);
 
       // Insert the new list into the cache.
       Cache.InsertNode(L, InsertPos);
     }
 
     return L;
   }
 
-  ImmutableList<T> add(const T& D, ImmutableList<T> L) {
+  LLVM_NODISCARD ImmutableList<T> add(const T& D, ImmutableList<T> L) {
     return concat(D, L);
   }
 
   ImmutableList<T> getEmptyList() const {
     return ImmutableList<T>(nullptr);
   }
 
   ImmutableList<T> create(const T& X) {

llvm/trunk/include/llvm/ADT/ImmutableMap.h

public:
     Factory(BumpPtrAllocator &Alloc, bool canonicalize = true)
         : F(Alloc), Canonicalize(canonicalize) {}
 
     Factory(const Factory &) = delete;
     Factory &operator=(const Factory &) = delete;
 
     ImmutableMap getEmptyMap() { return ImmutableMap(F.getEmptyTree()); }
 
-    ImmutableMap add(ImmutableMap Old, key_type_ref K, data_type_ref D) {
+    LLVM_NODISCARD ImmutableMap add(ImmutableMap Old, key_type_ref K,
+                                    data_type_ref D) {
       TreeTy *T = F.add(Old.Root, std::pair<key_type,data_type>(K,D));
       return ImmutableMap(Canonicalize ? F.getCanonicalTree(T): T);
     }
 
-    ImmutableMap remove(ImmutableMap Old, key_type_ref K) {
+    LLVM_NODISCARD ImmutableMap remove(ImmutableMap Old, key_type_ref K) {
       TreeTy *T = F.remove(Old.Root,K);
       return ImmutableMap(Canonicalize ? F.getCanonicalTree(T): T);
     }
 
     typename TreeTy::Factory *getTreeFactory() const {
       return const_cast<typename TreeTy::Factory *>(&F);
     }
   };

llvm/trunk/include/llvm/ADT/ImmutableSet.h

public:
 
     /// add - Creates a new immutable set that contains all of the values
     ///  of the original set with the addition of the specified value.  If
     ///  the original set already included the value, then the original set is
     ///  returned and no memory is allocated.  The time and space complexity
     ///  of this operation is logarithmic in the size of the original set.
     ///  The memory allocated to represent the set is released when the
     ///  factory object that created the set is destroyed.
-    ImmutableSet add(ImmutableSet Old, value_type_ref V) {
+    LLVM_NODISCARD ImmutableSet add(ImmutableSet Old, value_type_ref V) {
       TreeTy *NewT = F.add(Old.Root, V);
       return ImmutableSet(Canonicalize ? F.getCanonicalTree(NewT) : NewT);
     }
 
     /// remove - Creates a new immutable set that contains all of the values
     ///  of the original set with the exception of the specified value.  If
     ///  the original set did not contain the value, the original set is
     ///  returned and no memory is allocated.  The time and space complexity
     ///  of this operation is logarithmic in the size of the original set.
     ///  The memory allocated to represent the set is released when the
     ///  factory object that created the set is destroyed.
-    ImmutableSet remove(ImmutableSet Old, value_type_ref V) {
+    LLVM_NODISCARD ImmutableSet remove(ImmutableSet Old, value_type_ref V) {
       TreeTy *NewT = F.remove(Old.Root, V);
       return ImmutableSet(Canonicalize ? F.getCanonicalTree(NewT) : NewT);
     }
 
     BumpPtrAllocator& getAllocator() { return F.getAllocator(); }
 
     typename TreeTy::Factory *getTreeFactory() const {
       return const_cast<typename TreeTy::Factory *>(&F);