I would suggest we stick with doxygen for in-code documentation, which is what is already used in the (few) parts of the codebase that do have API documentation.
— Dr Peter M. Kelly pmke...@apache.org PGP key: http://www.kellypmk.net/pgp-key <http://www.kellypmk.net/pgp-key> (fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966) > On 12 May 2015, at 10:43 pm, jan i <j...@apache.org> wrote: > > On 12 May 2015 at 17:39, Gabriela Gibson <gabriela.gib...@gmail.com> wrote: > >> Hi Jan, >> >> I've been writing a toy "queueAPI" that is built with cmake, and it >> just so happens that setting up and adding DocBook services is the >> next job on that project list. >> >> I think that should make a nice demo case. >> > +1 It does not need to be a perfect demo, just so that we can understand > the flow, and where the information is kept. > > rgds > jan I. > > >> >> G >> >> >> On 5/12/15, jan i <j...@apache.org> wrote: >>> On 12 May 2015 at 13:52, Gabriela Gibson <gabriela.gib...@gmail.com> >> wrote: >>> >>>> Hi Peter, >>>> >>>> thanks for all the explanations :-) >>>> >>>> Further to Jan's suggestion, I think that the DF* library functions >>>> could benefit from DocBook comments, and be treated like an internal >>>> API. >>>> >>>> Whilst this is not for consumption for Corinthia users, it will be >>>> useful for devs in general and help to flatten the learning curve for >>>> newbies initially, and it's nice to just check on the generated HTML >>>> page to quickly find the correct tool or see easily if a better method >>>> is available. >>>> >>>> I wouldn't mind writing the initial cut thereof and it would help me >>>> understand the DF library better too. >>>> >>> I am not against the idea, just have a few comments: >>> - If DocBook is maintained outside the source (header file) itself, I >> would >>> never trust it. It is ok if it is extracted from the source file >>> - Dorte/I can make a subdir on our web for such documentation (divide in >>> internal/external/editor) >>> >>> >>> I never used DocBook, but different systems, could you please use a few >>> words/examples of the workflow, and how we integrate it >>> in the build process. >>> >>> thanks >>> jan I. >>> >>> >>>> G >>>> >>>> On 5/12/15, jan i <j...@apache.org> wrote: >>>>> Hi Peter. >>>>> >>>>> Thanks for these super explanations, even though I work on the >>>>> libraries >>>> at >>>>> the moment, they >>>>> were very interesting to read. >>>>> >>>>> Should these mails (in a slightly modified form) go into our Wiki, >>>>> maybe >>>> as >>>>> group "Thoughts >>>>> around the codebase" or something similar ? >>>>> >>>>> Keep up the fun >>>>> rgds >>>>> jan I. >>>>> >>>> >>>> >>>> -- >>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/ >>>> >>> >> >> >> -- >> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/ >>
