You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Daniel Rall <dl...@collab.net> on 2007/11/07 19:32:57 UTC
Introductory text for Doxygen-generated API documentation
While I agree that this text is a valuable addition, I really dislike
having it in svn_client.h (since it is applicable to a much broader
scope than svn_client.h). On IRC yesterday, we discussed using a
separate header file instead.
On Wed, 07 Nov 2007, hwright@tigris.org wrote:
> Author: hwright
> Date: Wed Nov 7 11:12:19 2007
> New Revision: 27661
>
> Log:
> Add a bit of introductory text to our Doxygen docs. The location of this text
> is somewhat arbitrary, it needs only live somewhere in the files which are
> processed by doxygen. I couldn't find a way to include this text somewhere
> outside of the source tree, but I think it is valuable to have some front
> matter to our generated API documentation.
>
> * subversion/include/svn_client.h:
> Add a comment which includes introductory text for the generated API docs.
>
>
> Modified:
> trunk/subversion/include/svn_client.h
>
> Modified: trunk/subversion/include/svn_client.h
> URL: http://svn.collab.net/viewvc/svn/trunk/subversion/include/svn_client.h?pathrev=27661&r1=27660&r2=27661
> ==============================================================================
> --- trunk/subversion/include/svn_client.h (original)
> +++ trunk/subversion/include/svn_client.h Wed Nov 7 11:12:19 2007
> @@ -4191,3 +4191,18 @@
> #endif /* __cplusplus */
>
> #endif /* SVN_CLIENT_H */
> +
> +/* The following comment adds some text to the main doxygen page. I've
> + * put it here, because I don't know of a better place. Feel free to
> + * move it if a more suitable home can be found. */
> +/**
> + * @mainpage Subversion Documentation
> + *
> + * This documentation covers the public APIs provided by the Subversion
> + * libraries. It is intended mainly for programmers, both those working
> + * on Subversion itself, as well as developers of 3rd-party applications
> + * intending to use these APIs. For more information about using Subversion,
> + * see the Subversion Book at http://svnbook.red-bean.com/.
> + *
> + * To learn more about Subversion, please visit http://subversion.tigris.org/.
> + */
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: svn-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: svn-help@subversion.tigris.org
Re: Introductory text for Doxygen-generated API documentation
Posted by Daniel Rall <dl...@collab.net>.
On Wed, 07 Nov 2007, C. Michael Pilato wrote:
> Hyrum K. Wright wrote:
> > Daniel Rall wrote:
> >> While I agree that this text is a valuable addition, I really dislike
> >> having it in svn_client.h (since it is applicable to a much broader
> >> scope than svn_client.h). On IRC yesterday, we discussed using a
> >> separate header file instead.
> >
> > We did. I went ahead and committed it, but we can move it around (or
> > change the text) as we see fit.
> >
> > We really don't have a single, all-inclusive "svn.h" header file, which
> > would be the ideal place to put something like this. Going through the
> > Doxygen manual, it appears that the introduction just needs to be
> > anywhere in the list of files which we document. In our case, these are
> > the public header files: subversion/include/*.h
> >
> > I have no objection to putting this text somewhere else in one of our
> > other public header files. I think creating a separate file just for
> > this purpose is a bit overkill. This is a limitation of the tool, which
> > we need to work around.
> >
> > Any suggestions?
>
> My mind always thinks of svn_types.h as sort of our "root header file". How
> about there?
Yeah, you certainly can't do much without svn_types.h; that's a better
spot than svn_client.h.
As I mentioned on IRC, I see a private Doxygen-specific header file to
be the best solution. I've configured Doxygen to handle that, and
moved the text into such a header in r27671.
Re: Introductory text for Doxygen-generated API documentation
Posted by "C. Michael Pilato" <cm...@collab.net>.
Hyrum K. Wright wrote:
> Daniel Rall wrote:
>> While I agree that this text is a valuable addition, I really dislike
>> having it in svn_client.h (since it is applicable to a much broader
>> scope than svn_client.h). On IRC yesterday, we discussed using a
>> separate header file instead.
>
> We did. I went ahead and committed it, but we can move it around (or
> change the text) as we see fit.
>
> We really don't have a single, all-inclusive "svn.h" header file, which
> would be the ideal place to put something like this. Going through the
> Doxygen manual, it appears that the introduction just needs to be
> anywhere in the list of files which we document. In our case, these are
> the public header files: subversion/include/*.h
>
> I have no objection to putting this text somewhere else in one of our
> other public header files. I think creating a separate file just for
> this purpose is a bit overkill. This is a limitation of the tool, which
> we need to work around.
>
> Any suggestions?
My mind always thinks of svn_types.h as sort of our "root header file". How
about there?
--
C. Michael Pilato <cm...@collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
Re: Introductory text for Doxygen-generated API documentation
Posted by "Hyrum K. Wright" <hy...@mail.utexas.edu>.
Daniel Rall wrote:
> While I agree that this text is a valuable addition, I really dislike
> having it in svn_client.h (since it is applicable to a much broader
> scope than svn_client.h). On IRC yesterday, we discussed using a
> separate header file instead.
We did. I went ahead and committed it, but we can move it around (or
change the text) as we see fit.
We really don't have a single, all-inclusive "svn.h" header file, which
would be the ideal place to put something like this. Going through the
Doxygen manual, it appears that the introduction just needs to be
anywhere in the list of files which we document. In our case, these are
the public header files: subversion/include/*.h
I have no objection to putting this text somewhere else in one of our
other public header files. I think creating a separate file just for
this purpose is a bit overkill. This is a limitation of the tool, which
we need to work around.
Any suggestions?
-Hyrum