Merge pull request #647 from leapmotion/fix-docs

Fix doxygen warnings

autowiring/AutoPacket.h

@@ -128,7 +128,8 @@ class AutoPacket:
   /// <summary>
   /// Updates subscriber statuses given that the specified type information has been satisfied
   /// </summary>
-  /// <param name="info">The decoration which was just added to this packet</param>
+  /// <param name="lk">The unique_lock used to control the synchronization level</param>
+  /// <param name="disposition">The decoration that was just updated</param>
   /// <remarks>
   /// This method results in a call to the AutoFilter method on any subscribers which are
   /// satisfied by this decoration.  This method must be called with m_lock held.
@@ -274,6 +275,7 @@ class AutoPacket:
   /// <summary>
   /// Shared pointer specialization of const T*&, used to obtain the underlying shared pointer for some type T
   /// </summary>
+  /// <param name="out">Receives the requested decoration, or else nullptr</param>
   /// <param name="tshift">The number back to retrieve</param>
   /// <remarks>
   /// This specialization cannot be used to obtain a decoration which has been attached to this packet via
@@ -623,6 +625,8 @@ class AutoPacket:
   /// <summary>
   /// Blocks until the specified descriptor is satisfied
   /// </summary>
+  /// <param name="cv">A condition variable used to perform the wait</param>
+  /// <param name="inputs">The inputs whose satisfaction state is to be considered</param>
   /// <param name="duration">
   /// The amount of time to wait.  If set to std::chrono::nanoseconds::max, this method will block indefinitely
   /// </param>
@@ -638,6 +642,8 @@ class AutoPacket:
   /// Blocks until the passed lambda function can be called
   /// </summary>
   /// <param name="cv">A condition variable that can be signalled when the wait condition has expired</param>
+  /// <param name="autoFilter">The filter to be blocked on</param>
+  /// <param name="duration">The maximum amount of time to wait</param>
   /// <returns>
   /// True on success, false if a timeout occurred
   /// </returns>

autowiring/AutoPacketFactory.h

@@ -230,6 +230,7 @@ class AutoPacketFactory:
   void ResetPacketStatistics(void);
 };
 
+// @cond
 // Extern explicit template instantiation declarations added to prevent
 // exterior instantation of internally used template instances
 extern template struct SlotInformationStump<AutoPacketFactory, false>;
@@ -238,3 +239,4 @@ extern template std::shared_ptr<AutoPacketFactory> autowiring::fast_pointer_cast
 extern template class RegType<AutoPacketFactory>;
 extern template struct autowiring::fast_pointer_cast_blind<CoreObject, AutoPacketFactory>;
 extern template struct autowiring::fast_pointer_cast_initializer<CoreObject, AutoPacketFactory>;
+// @endcond

autowiring/BasicThread.h

@@ -11,7 +11,6 @@ struct BasicThreadStateBlock;
 class BasicThread;
 class CoreContext;
 
-/// \internal (until ElevatePriority feature is implmented on all platforms)
 /// <summary>
 /// Thread priority classifications from low to high.
 /// </summary>
@@ -132,7 +131,8 @@ class BasicThread:
   /// <summary>
   /// Performs all cleanup operations that must take place after DoRun()
   /// </summary>
-  /// <param name="pusher">The last reference to the enclosing context held by this thread</param>
+  /// <param name="ctxt">The last reference to the enclosing context held by this thread</param>
+  /// <param name="refTracker">A reference tracker held for as long as the cleanup operation is incomplete</param>
   virtual void DoRunLoopCleanup(std::shared_ptr<CoreContext>&& ctxt, std::shared_ptr<CoreObject>&& refTracker);
 
   /// \internal Only implemented on Windows (as of 0.4.1).

autowiring/ExceptionFilter.h

@@ -72,6 +72,7 @@ class ExceptionFilter
   /// <summary>
   /// This is an exception filter for exceptions thrown during a call to Fire
   /// </summary>
+  /// <param name="pJunctionBox">The junction box generating the exception</param>
   /// <param name="pRecipient">The target of the call</param>
   /// <remarks>
   /// Implementors can use "throw" with no arguments to trigger a rethrow of the originating exception.

devguide/AutoFilters.md

@@ -20,7 +20,7 @@ The context forms the boundaries of a filter network. There are two ways around
 
 You can create a filter with any object by implementing a function named AutoFilter. The arguments of the function declares both the input types of the filter and the output types. Const references and arguments passed by value are inputs. Non-const references are output types. The following example creates a class implementing an AutoFilter that takes two inputs and has one output:
 
-  \include snippets/AutoFilter_BasicFilter.txt
+\include snippets/AutoFilter_BasicAutoFilter.txt
 
 The function is called when instances of types T and Q are added to the packet. On exit from the function, the type W is added to the packet.
 

devguide/Files.dox

@@ -13,6 +13,8 @@
 
 /// \file auto_prev.h
 
+/// \file AutowiringDebug.h
+
 /// \file AutoConfig.h
 
 /// \file AutoNetServer.h
@@ -40,10 +42,6 @@
 
 /// \file BoltBase.h
 
-/// \file ContextCreator.h
-
-/// \file ContextCreatorBase.h
-
 /// \file ContextEnumerator.h
 
 /// \file ContextMember.h

devguide/snippets/AutoFilter_ImageNet.txt

@@ -0,0 +1,71 @@
+struct Image{};
+struct RawImage: public Image{};
+struct BlurredImage: public Image{};
+struct CircleList{};
+struct LineList{};
+struct FeatureList{};
+
+class Camera{
+    public:
+        AutoRequired<AutoPacketFactory> packetGenerator;
+        void produceImage(int id){
+            RawImage raw;
+            std::cout << "Produced raw image # " << id << std::endl;
+            auto packet = packetGenerator->NewPacket();
+            packet->Decorate(raw);
+        }
+};
+
+class BlurFilter{
+    public:
+        void AutoFilter(const RawImage img, BlurredImage &blurred){
+            blurred = blur(img);
+        }
+        BlurredImage blur(const RawImage raw){
+            std::cout << "Blurred image." << std::endl;
+            return BlurredImage();
+        }
+};
+
+class CircleFinder {
+    public:
+        void AutoFilter(const BlurredImage img, CircleList &circles){
+            circles = findCircles(img);
+        }
+        CircleList findCircles(const BlurredImage blurred){
+            std::cout << "Found circles." << std::endl;
+            return CircleList();
+        }
+};
+
+class LineFinder {
+    public:
+        AutoRequired<AutoPacketFactory> packetGenerator;
+        void AutoFilter(const BlurredImage img, LineList &lines){
+            lines = findLines(img);
+        }
+        LineList findLines(const BlurredImage blurred){
+            std::cout << "Found lines." << std::endl;
+            return LineList();
+        }
+};
+
+class GraphOut {
+    public:
+        void AutoFilter(const CircleList circles, const LineList lines, AutoPacket &packet){
+            std::cout << "Received final packet with lines and circles. " << std::endl;
+        }
+};
+
+AutoCreateContext ctxt;
+ctxt->SetCurrent();
+
+AutoRequired<Camera> camera;
+AutoRequired<BlurFilter> blurFilter;
+AutoRequired<CircleFinder> circleFilter;
+AutoRequired<LineFinder> lineFilter;
+AutoRequired<GraphOut> graphOutput;
+
+ctxt->Initiate();
+
+camera->produceImage(1);

examples/AutoFilterTutorial.0.0.cpp

@@ -18,12 +18,10 @@
 /// deal only with ordinary input and output.
 ///
 /// This tutorial will define and instantiate a simple filter network.
-/// @code{.cpp}
 #include <autowiring/Autowired.h> // Needed for Autowiring classes.
 #include <cmath>                  // Needed for std::round.
 #include <cstdlib>                // Needed for std::atof.
 #include <iostream>               // Needed for std::cout.
-/// @endcode 
 /// We will define several filters connecting several data structures (really they can be any C++ type), rendering
 /// a linear sequence of processing.
 ///
@@ -34,57 +32,50 @@
 ///
 /// In particular, this filter parses the string as a decimal value and stores it in double-precision floating
 /// point format in the output parameter.
-/// @code
 class StringToDouble {
 public:
   void AutoFilter (std::string input, double &output) {
     output = std::atof(input.c_str());
     std::cout << "StringToDouble received std::string value \"" << input << "\" and has set its output param to double value " << output << ".\n";
   }
 };
-/// @endcode 
+
 /// This filter takes a double as input and produces an int as output.  In particular, the output is the rounded
 /// value of the input.
-/// @code
 class DoubleRounder {
 public:
   void AutoFilter (double input, int &output) {
     output = static_cast<int>(std::round(input));
     std::cout << "DoubleRounder received double value " << input << " and has set its output param to int value " << output << ".\n";
   }
 };
-/// @endcode 
+
 /// This filter takes an int as input and has no output.  It simply prints the value of the input.
-/// @code
 class IntPrinter {
 public:
   void AutoFilter (int value) {
     std::cout << "IntPrinter received int value " << value << ".\n";
   }
 };
-/// @endcode 
+
 /// To demonstrate this filter network, we will perform the necessary initialization and context member injection
 /// within the main function.
-/// @code
 int main () {
-/// @endcode
+
 /// A global context is created by default, and is the default current context.  We must initialize that context
 /// before proceeding.
-/// @code
   AutoCurrentContext()->Initiate();
-/// @endcode
+
 /// Each of the filters must be injected into the context in which they'll operate.  In this case, we're only working
 /// with the global context.  The `AutoRequired` method is what accomplishes that injection.
-/// @code
   AutoRequired<StringToDouble>();
   AutoRequired<DoubleRounder>();
   AutoRequired<IntPrinter>();
-/// @endcode
+
 /// If a context has any members, then the context automatically includes an AutoPacketFactory type. This
 /// can be used to create new packets in the AutoFilter network.
-/// @code
   Autowired<AutoPacketFactory> factory;
-/// @endcode
+
 /// `AutoPacket` is the mechanism which runs filter networks.  An instance of AutoPacket corresponds with one execution
 /// of the corresponding filter network.  The packet can be 'decorated' with a value of a particular type.  This means
 /// that that type is present during this execution of the filter network as an input parameter to whatever AutoFilter
@@ -93,39 +84,34 @@ int main () {
 /// packet.
 ///
 /// Using the factory, create a new AutoPacket so that we may run the filter network.
-/// @code
   std::shared_ptr<AutoPacket> packet = factory->NewPacket();
-/// @endcode
+
 /// Now decorate the packet with an `int`.  This will cause the `AutoFilter` methods which only require a single `int`
 /// input to be called.  We should expect to see "IntPrinter received int value 42." printed to std::cout at this point.
-/// @code
   packet->Decorate(42);
   std::cout << '\n'; // To make the separation between packets' executions clear in the console output.
-/// @endcode
+
 /// Create a new packet so that we may run the filter network again.  Note that `packet` is a `std::shared_ptr<AutoPacket>`,
 /// and so this assignment deletes the old instance.  Decorate the packet again, but this time with a `double` value, thereby
 /// calling the `DoubleRounder` filter, which in turn outputs an `int`, which calls the `IntPrinter` filter, generating output
 /// to std::cout.  This demonstrates that a filter network doesn't have a fixed input interface -- inputs can be provided at
 /// any point.  Of course, an `AutoFilter` method will be called only when all of its inputs are present on a packet.
-/// @code
   packet = factory->NewPacket();
   packet->Decorate(101.1);
   std::cout << '\n';
-/// @endcode
+
 /// Repeat the process, but decorate the packet with a value whose rounded value is different.
-/// @code
   packet = factory->NewPacket();
   packet->Decorate(101.9);
   std::cout << '\n';
-/// @endcode
+
 /// Repeat the process, but decorate the packet with a std::string value.
-/// @code
   packet = factory->NewPacket();
   packet->Decorate(std::string("45954.1"));
 
   return 0; // Return with no error.
 }
-/// @endcode
+
 /// The output of this program is:
 ///
 ///     IntPrinter received int value 42.

examples/AutoFilterTutorial.1.0.cpp

@@ -16,12 +16,11 @@
 /// - `const std::shared_ptr<const T>`
 /// - `const std::shared_ptr<const T> &`
 ///
-/// @code{.cpp}
 #include <autowiring/Autowired.h> // Needed for Autowiring classes.
 #include <iostream>               // Needed for std::cout.
 #include <string>                 // Needed for std::string.
 #include <unordered_set>          // Needed for std::unordered_set.
-/// @endcode
+
 /// We will now define several structures having AutoFilter methods.  Note that classes and structs are essentially equivalent
 /// in C++ (besides the default access specifiers), so using struct here doesn't indicate anything special, it just allows us
 /// to avoid having to explicitly write the `public:` access specifier.
@@ -30,7 +29,6 @@
 /// a reflective message indicating the struct and the type, and then store the input value.  The input values that we will
 /// send will indicate the type used to decorate the packet used in the execution.  This way, we can verify that the expected
 /// inputs were received by the expected context members.
-/// @code
 struct Hippo1 {
   void AutoFilter (std::string input) {
     std::cout << "Hippo1::AutoFilter(std::string) was called with value: \"" << input << "\"\n";
@@ -91,11 +89,10 @@ int main () {
   Autowired<AutoPacketFactory> factory;
   // Declare a packet to use in the following code blocks.
   std::shared_ptr<AutoPacket> packet;
-/// @endcode
+
 /// At this point we will execute the filter network a number of times, each with a different type related to `std::string`,
 /// in order to observe which filters are executed.  The first six executions demonstrate the types that are equivalent to
-/// `std::string` as input parameters (in which we expect only `Hippo#::AutoFilter` to be called).
-/// @code  
+/// `std::string` as input parameters (in which we expect only `Hippo#::AutoFilter` to be called). 
   {
     packet = factory->NewPacket();
     std::cout << "Decorating packet with instance of `std::string`:\n";
@@ -143,9 +140,8 @@ int main () {
     packet->Decorate(s);
     std::cout << '\n';
   }
-/// @endcode
+
 /// Verify that the accumulated values in the `m_received_input_decoration_types` for each context member are what we expect.
-/// @code
   {
     std::unordered_set<std::string> expected_hippo_inputs({
       "std::string",
@@ -173,7 +169,7 @@ int main () {
 
   return 0; // Return with no error.
 }
-/// @endcode
+
 /// The output of this program should be (with possibly a different ordering of `AutoFilter` calls):
 ///
 ///     Decorating packet with instance of `std::string`: