DPDK patches and discussions
 help / color / mirror / Atom feed
From: Thomas Monjalon <thomas@monjalon.net>
To: "Chautru, Nicolas" <nicolas.chautru@intel.com>
Cc: "Mcnamara, John" <john.mcnamara@intel.com>,
	"Kovacevic, Marko" <marko.kovacevic@intel.com>,
	"dev@dpdk.org" <dev@dpdk.org>
Subject: Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide
Date: Thu, 18 Jul 2019 17:09:17 +0200	[thread overview]
Message-ID: <65166887.pMNS0f2l0f@xps> (raw)
In-Reply-To: <1183128033837D43A851F70F33ED5C575C1FD52C@FMSMSX109.amr.corp.intel.com>

18/07/2019 16:59, Chautru, Nicolas:
> From: Thomas Monjalon [mailto:thomas@monjalon.net] 
> >18/07/2019 15:33, Chautru, Nicolas:
> >> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> >> >Anyway all the documentation about the API details should be removed.
> >> >The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments.
> >> 
> >> Thanks Thomas. 
> >> These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure. 
> >> I have just pushed a parallel patch here : 
> >> https://patches.dpdk.org/patch/56715/
> >
> >Sorry, I am not sure to understand.
> >You want to keep all this information?
> 
> I would rather yes. I can see your point with some redundancy between code and documentation, but the bbdev.rst documentation is arguably clearer as it is : the detailed information in paragraphs puts into context some of the information captured in a nice and concise table. Clearer than having to go back and forth in doxygen capturing some of this in a less compact format (which still has its own complementary value). Matter of opinion, let me know if you have a fundamental concern with keeping such table in that document. 

I am not sure it is clearer to document all parameters in rst.

The main concern is about maintainability.
When we change something in the code, we change the doxygen
and we forget the rst guide.

The other concern is that maybe the doxygen is not complete.

My advice is to reference the doxygen when the information is the same.



  reply	other threads:[~2019-07-18 15:09 UTC|newest]

Thread overview: 14+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-07-17 22:01 Thomas Monjalon
2019-07-18 13:33 ` Chautru, Nicolas
2019-07-18 13:47   ` Thomas Monjalon
2019-07-18 14:59     ` Chautru, Nicolas
2019-07-18 15:09       ` Thomas Monjalon [this message]
2019-07-18  6:24 Nicolas Chautru
2019-07-18 13:53 ` Thomas Monjalon
2019-07-18 14:43   ` Chautru, Nicolas
2019-07-18 15:01     ` Thomas Monjalon
2019-07-18 15:09       ` Chautru, Nicolas
2019-07-18 13:57 ` Thomas Monjalon
2019-07-18 14:51   ` Chautru, Nicolas
2019-07-18 15:05     ` Thomas Monjalon
2019-07-18 21:49 ` Thomas Monjalon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=65166887.pMNS0f2l0f@xps \
    --to=thomas@monjalon.net \
    --cc=dev@dpdk.org \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.com \
    --cc=nicolas.chautru@intel.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).