[clang-tools-extra] r183417 - cpp11-migrate: Docs refresh

[Sean Silva]

On Thu, Jun 6, 2013 at 10:15 AM, Vane, Edwin <edwin.vane at intel.com> wrote:

>
>
> > -----Original Message-----
> > From: Sean Silva [mailto:silvas at purdue.edu]
> > Sent: Thursday, June 06, 2013 12:46 PM
> > To: Vane, Edwin
> > Cc: cfe-commits at cs.uiuc.edu
> > Subject: Re: [clang-tools-extra] r183417 - cpp11-migrate: Docs refresh
> >
> > Sorry I didn't get to this while it was still in Phabricator. In the
> future, please split
> > up logically separate changes into separate patches (this applies even
> for
> > documentation).
>
> What do you see as logically separate changes in this patch?
>

I was able to glean the following independent changes from your patch and
your description of the changes; there may be others I missed. Items marked
with `*` could have been committed directly without pre-commit review since
they are "obvious".

1* The change to docs/AddOverrideTransform.rst
2* Changing the title of docs/cpp11-migrate.rst
3* Factoring out the usage to docs/MigratorUsage.rst
4* Adding the forgotten link to :doc:`AddOverrideTransform`
5* Changing the header level (from subsection to section) of
`Transformations`
6 Adding the "Getting Started" section
7 Adding the "Getting Involved" section
8* Splitting the options into general and transform-specific options.
9* Documenting new command line options (maybe pre-commit review this one
for extra feedback on the text).
10* Adding the intro paragraph to the "Transformations" section.

If you hadn't mentioned in the commit message that you introduced
documentation for new command line options, I wouldn't have noticed since
in the same patch you both reorganized the section containing the command
line options and moved it to another file. (I still have no idea which new
options were documented...)


>
> > +If you find a bug
> > +
> > +.. raw:: html
> > +
> > +  <input type="button" id="logbug" value="Log a Bug!" />  <script
> > + type="text/javascript"
> > + src="https://cpp11-migrate.atlassian.net/s/en_USpfg3b3-1988229788/6095
> > + /34/1.4.0-m2/_/download/batch/com.atlassian.jira.collector.plugin.jira
> > + -issue-collector-plugin:issuecollector/com.atlassian.jira.collector.pl
> > + ugin.jira-issue-collector-plugin:issuecollector.js?collectorId=5081387
> > + 4"></script>  <script type="text/javascript">window.ATL_JQ_PAGE_PROPS
> > + =  {
> > +    "triggerFunction": function(showCollectorDialog) {
> > +      //Requries that jQuery is available!
> > +      jQuery("#logbug").click(function(e) {
> > +        e.preventDefault();
> > +        showCollectorDialog();
> > +      });
> > +    }};
> > +  </script>
> >
> >
> > Could you just link to a "file a new bug" form instead of spewing this
> raw markup
> > and modal dialog into the page?
>
> I'm afraid that's how the issue collector works. There is no separate page
> for logging bugs anonymously.


Please file an issue with Atlassian. This is ridiculous.


> I can just disable anonymous bug loggings I just wanted to make it as easy
> as possible to log bugs.
>

It's not really clear to me how disabling anonymous bug logging would make
it as easy as possible to log bugs. Anyway, generally you want to balance
ease of logging bugs (increase fraction of people experience bugs that
report them) with the ability to follow up with the person so that the bug
can be made actionable (increase fraction of reported bugs that are
actionable), hence anonymous bug reports are not necessarily the best
choice (they may be adequate in this scenario).


>
> > Just curious, but why do you guys have a separate bug tracker for cpp11-
> > migrate?
>
> Cpp11-migrate.atlassian.net is not just a bug tracker. It's our main way
> of doing project tracking. If people log bugs at llvm.org/bugs I just
> manually copy them into the project tracker anyway.
>
> >
> >
> >  Transformations
> > -===============
> > +---------------
> >
> >
> > Please stick to the standard adornments as laid out in
> > llvm/docs/SphinxQuickstartTemplate.rst
>
> I made this change because Sphinx was getting the section levels wrong.
> Sphinx has no absolute mapping between the section level and a markup so it
> tries to infer. I'll see if I can find another workaround.
>

It seems like you are using ------------ for "section" in this document.
Just use ========== to indicate "section".


>
> > Tiny nit:
> >
> > +In addition to the compiler arguments you usually build your code with,
> > +you must provide the option for enabling C++11 features. For clang and
> > +versions of gcc ≥ v4.8 this is ``-std=c++11``.
>
> I take it Unicode is not allowed then? I wanted U+2265.
>
>
We allow unicode. In this case, I would have just done >=, but it's not a
big deal.

-- Sean Silva
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130607/13e855c9/attachment.html>