These are chat archives for bluescarni/pagmo_reborn

12th
Jun 2016
Dario Izzo
@darioizzo
Jun 12 2016 08:13
@bluescarni Ah ok, sorry I did not get you wanted to change those too (I was thinking sparsity). For consistency I assume ... You can do them in your branch then .... then I guess I can merge from it
Francesco Biscani
@bluescarni
Jun 12 2016 08:51
alright
btw it is actually possible to inspect the function signature in Python, this could help giving better error messages for the UDP in Python
but I'll leave this for later
Dario Izzo
@darioizzo
Jun 12 2016 09:33
right .. cool
Francesco Biscani
@bluescarni
Jun 12 2016 11:16
so for some instances of what I mean about the docs
Francesco Biscani
@bluescarni
Jun 12 2016 11:53
just a collection of random things
  • I had initially done the Python docs according to a certain markup style (it does not matter which one). Then I noticed when you committed the cmaes docs they were adopting another convention (stupid example: markup of types using double backticks vs no special markup for types), so I went back and modified the existing docs. I don't care which style we use, as long as we adopt one and we stick to it consistently, and I'd like not to have to spend time policing this if possible :)
  • we still don't have full docs on the exposed problems/algorithm, IMO we should have a consistent behaviour of the public API. Either we document it all at the same way (which means adding params, return values, throws, etc.) it or we don't.
  • at one point we decided we should have error messages like this one already implemented in problem:
                  pagmo_throw(std::logic_error,"the user-defined problem does not support seed setting: "
                      "either it does not provide the 'set_seed()' method or its 'has_set_seed()' method "
                      "returns false\n\nThe expected prototypes for 'set_seed()' are:\n"
                      "C++: 'void set_seed(unsigned int)'\n"
                      "Python: 'set_seed(seed)'");
    this is okish maybe for the set_seed() function, but it does not really inform for instance on what the argument types should be, nor what the functions should return. This is a problem for functions like the gradient for instance. We could add this info to the message of course, but then we have the same information in 3 different places in the docs, and if we ever need to change it it's gonna be madness. This is all information that IMO should be in the web documentation. Are we expecting one to be able to start writing problems "blindly" from the command line without ever opening up the PyGMO docs? I think we need to have a consistent behaviour and intent about this, otherwise we will have a hodgepodge of documentation. It's clear that we have conflicting ideas about the style and scope of the docs, so I think we need to find a common ground before making a mess.
  • regarding the throws: there are many places were only a subset of throws are documented. For instance, the pop ctor from problem does not mention it could throw from creating the problem. the best/worst idx do not document that they could throw from the functions used for the sorting. The second overloads of sort_population_con() does not mention it could throw anything thrown by the first overload. And so on. Again, I started noticing this after starting to write the Python docs and asking myself what and how could throw for documenting it on the Python side. About this, I am open to the idea of eliminating the throws specifications at all, because honestly over the years I have used them they have not been of great practical value. Better to erase them altogether than having them half-assed :)
  • there's lots of glitches/inconsistencies on the doxygen side of the docs. Again, different markup stylings, the fact that sometimes there are round brackets when referencing methods sometimes there aren't, the random use of rulers, the fact that the @note command sometimes used with a : sometimes not, phrases sometimes terminating with a . sometimes not, etc.
so it's nothing major, just a lot of small things which often absorb sizeable portions of my pagmo coding time which I suppose I could use in a more useful way :)
Dario Izzo
@darioizzo
Jun 12 2016 12:24
  • The python docs of CMAES used the same convention as the last entry in the file docstrings.cpp which was rosenbrock. I assumed it was "the" one convention. Did not notice that you used two different conventions in the same file ...
  • On the problems and algorithms docs. I choose not to document getters and setters when obvious (as in they are one of type m_name = value; or return m_name;). This type of docs make the appearance of the doc page more compact as it avoids the use of space for the obvious shortening the wall of text. But I am fine if you want to add them.
  • We can remove the expected prototype thing and put a ref to the online docs maybe? Or just remove it altogether and invite verbally to check the online docs.
  • For the throws: I would propose to remove all throws that are unspecified, leaving the ones that are in the body. Does this make sense?
  • the glitches and inconsistencies will always be there and will be slowly fixed in time version after version ... I personally do not think it is of much importance to have all sentences ended with . or not, all @note followed by a column or not etc.... It certainly adds a feeling of professionalism, but as you said are all things that if enforced absorb too much time that could be otherwise be used better.
On the the fact that writing docs properly is less interesting than coding, I agree. I personally infact tend to stop caring after having spent some time as otherwise I could go on for 99% of the time :)