Thanks for the example from you code, Roger. Because I am working with code where the comments have already been written without rst format, I have to either add the rst notation in the original source as you have done (the ideal method) and then automate the extraction or add the rst notation after extraction. At the moment the copy/paste process seems the least of my problems - the main issue being the need for rst formatting of the comments - a process that requires tedious and precise oversight and is subject to all kinds of unpredicatable variations.
Hopefully the potential Java extension that Georg has spoken about will arrive before I ever have to go through this again. On Fri, Feb 26, 2010 at 7:42 PM, Roger Binns <[email protected]> wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Chris Collins wrote: > > Good idea. In case you're not familiar, Java has an automatic > > documentation feature called JavaDoc. > > I used Java from around its 1.0 days and consequently am very familiar with > Javadoc. It was the first time a mainstream language had a single syntax > and convention for doing doc with source. (Yes other languages had > something similar, but they were never arguably mainstream. I don't think > Java had anything unique - it was mainly a repackaging of lots of other > pre-existing techniques but happened at the right time.) > > > I guess I could try to write a program to parse the JavaDocs > > You don't need to have actual Javadoc in your code. Here is an example of > what I do: > > http://code.google.com/p/apsw/source/browse/src/connection.c#232 > > A processor just finds all comments that begin with /** at column one and > extracts them. Note how the comments are in sphinx/rst format already. > > > So copy/paste will have to do for now, I suppose. > > My point is that you can you automate the copy/paste. > > > Not sure what you mean by "run it through an indent tool", though. > > If your formatting is consistent then your automation can just follow that. > For example in my case you can see the relevant comments start in column > 1. > I have some other code that also knows the functions are named like > Object_method, also starting in column 1 so they can easily play with the > source without having to use a full blown parser. > > The point of indent is that if your code is not consistent then running > indent on it will make the formatting consistent, saving you a lot of > hassle. > > Roger > -----BEGIN PGP SIGNATURE----- > Version: GnuPG v1.4.9 (GNU/Linux) > Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org > > iEYEARECAAYFAkuIanYACgkQmOOfHg372QSnngCfZ8IQNme/5LYjFhdO45BrCqrf > 6WsAoJyHlOUHck/fI8yPcaCAgkLOgNXT > =4nMq > -----END PGP SIGNATURE----- > > -- > You received this message because you are subscribed to the Google Groups > "sphinx-dev" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]<sphinx-dev%[email protected]> > . > For more options, visit this group at > http://groups.google.com/group/sphinx-dev?hl=en. > > -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
