Hi.
Doxygen is a favorite of mine, it does what I like (most of the time). We do need some guidelines in the wiki, with examples, how/what to document, but apart from that, just go ahead. rgds jan I. On 12 May 2015 at 18:43, Gabriela Gibson <[email protected]> wrote: > 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/ >
