Hi Peter, this is funny --- I DID confuse DocBook and Doxygen. I _meant_ Doxygen, I used it before, but for some reason I researched DocBook instead and it stuck. So much for brand recognition.
I nearly learned to set up the wrong thing there %-) G On 5/12/15, Peter Kelly <[email protected]> wrote: > 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 > [email protected] > > 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 <[email protected]> wrote: >> >> On 12 May 2015 at 17:39, Gabriela Gibson <[email protected]> >> 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 <[email protected]> wrote: >>>> On 12 May 2015 at 13:52, Gabriela Gibson <[email protected]> >>> 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 <[email protected]> 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/ >>> > > -- Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
