Renato Forti wrote:
Here are the online docs to the library:
http://www.dokfile.com/appbeta3/docs/libs/application/doc/html/index.html
I had a quick look at the documentation and I certainly think your
library could be useful. I do have one concern about the API, and a
few remarks about the documentation.
My concern about the API:
In order to create an interactive application, the body of main would
be
return application< my_application<myapp> >( args(argc, argv) )();
while for a server it would be
return application< application_type,
my_application<myapp> >( args(argc, argv) )();
.
I find this counterintuitive for three reasons. The first is that
my_application appears to be a template provided by the application
library, so it isn't "mine" at all. I only created myapp so that is
the only entity that should be allowed to have "my" in the name.
Secondly, I need two nested templates in order to launch my
application class. There is no immediately obvious reason why it
couldn't be just a single template.
The third reason is that I need to specify the application type for a
server but not for an interactive application, and that this optional
template parameter comes before the required parameter, i.e. the
template that actually wraps my application class.
Concluding, I would find the following interface much more natural:
return interactive_app<myapp>(args(argc, argv))();
return server_app<myapp>(args(argc, argv))();
for interactive applications and server applications, respectively.
Perhaps this isn't possible, but then at least the very start of the
documentation should give the user an understandable reason why the
interface needs to look so complicated. In any case, please let the
optional template parameters come after the required parameters.
My remarks about the documentation:
The English leaves a lot to be improved upon. There are eye-catching
typos, such as "Handlres" in one of the section titles and "avector"
in the two minute introduction, as well as many subtle ellipses and
other syntactical errors that make the text a bit unnatural and harder
to read. This may not seem important, because it doesn't make your
library any less valid and it probably wouldn't affect the outcome of
a future review (much), but it will be easier to get a review at all
if you improve the language. Potential reviewers and review managers
may get the impression they can't take your library seriously after a
first glance at the documentation, so I think it would be advisable to
give this first priority. I would recommend getting help from a
(near-)native speaker to clear up the syntax.
There are lots of exclamation marks in the text. This gives a
"screamy" and not-so-serious appearance.
I compared the Windows and Unix tutorials and the example code is
completely identical, except for a single line in the blocking stop at
the end. That difference isn't even strictly necessary as it is the
omission of a line that would be ignored in Unixy systems anyway. I
think you should merge the tutorials, both to show that your library
meets the goal to write portable applications and to illustrate how a
decision in the code affects both platforms, regardless of what
platform the user is most interested in.
Hope this helps!
-Julian
