Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-4001

Write next-generation stack doc writing guide

    XMLWordPrintable

Details

    Description

      Write a guide in the prototype LSST Stack Docs (https://github.com/lsst-sqre/lsst_stack_docs) covering how to document the LSST Stack under the new doc infrastructure.

      This exercise will implicitly involve designing how the new docs will work. Content includes:

      1. How to write a user guide to a package (both content wise and in terms of organizing a package's doc files)
      2. How to write python doc strings
      3. Coverage of reStructuredText and Sphinx as implemented by the LSST Stack Docs.

      Attachments

        Activity

          This PR for DM-4001 adds a section on writing stack documentation in the new Sphinx-based documentation architecture. I've included pages on the reStructuredText markup language, how to write package documentation, and how to write documentation embedded in Python and C++ source files.

          See the documentation online at http://docs.lsst.codes/en/tickets-dm-4001/development/docs/index.html

          jsick Jonathan Sick added a comment - This PR for DM-4001 adds a section on writing stack documentation in the new Sphinx-based documentation architecture. I've included pages on the reStructuredText markup language, how to write package documentation, and how to write documentation embedded in Python and C++ source files. See the documentation online at http://docs.lsst.codes/en/tickets-dm-4001/development/docs/index.html

          As a reST newbie I would ask you to consider some rearrangement of content. I found the beginning quite hard to understand due to lack of examples and context. In particular I found it unenlightening and intimidating to hear about Roles, Directives or wrapping rules before having any idea what they are used for or what reST looks like.

          I suggest you start with basic formatting first, e.g. inline text styling, lists, possibly links, and sections (roughly in that order). Then, after we have the basics you can talk about Roles and Directives with something concrete to refer back to. However, if you prefer the current arrangement then it might suffice to start with an example (showing the source and the formatted result).

          I am quite concerned about your suggestion to use 3 spaces for indenting. Our source code uses 4 spaces/tab stop and it would be much easier to use 4 spaces when writing reST in source code. Even for pure reST files it would be handy to stick with 4 spaces, since one need to fine-tune the editor based on file type, and since then one can use the same standard in source code and out, and copy/past reST between the two without worrying about changing the indentation.

          Thank you for the section "inline styles can't be nested" and the next section. I found that very helpful, as I often run into this, e.g. when using markdown. However, your inline example doesn't quite nest properly; the final two characters (*`) should be swapped. A typo?

          I suggest not using a footnote for monospace in source code, since developers will write a huge fraction of their reST in source code. I suggest listing both options in the same place, e.g.:
          monospace in source code uses single backticks: ...
          monospace in pure reST files uses double backticks: ...
          It is a pity that distinction exists, but I assume we are stuck with it.

          Sections: this would be clearer by just showing the examples (without the initial list) and, if possible, the results. For instance I have no idea what "Page title: # with overline" means until I see the example below, and the example is sufficient (though it is not clear to me if the leading and trailing # are needed or convention or...). Hence I would ditch the list, or integrate the examples with the list items. If you do keep the list, please don't number it, as the numbers don't seem to add information.

          I realize showing results will be hard, since cluttering the text with extra section dividers could be confusing. Inset graphics would be great, but might be too much work. A link to a page showing the results of the example would probably suffice. (I wish we could use in-line commands, such as "h1.", instead of underlines, but that's just me.)

          What does this note mean: "Note that reST will automatically map section characters to HTML header levels based on the order in which they appear. Using this hierarchy, however, is strongly recommended for consistency"?

          I don't understand your example of a section label. What is the name of the section? Is it "section-label" or is that a reST command and the name is "Title of the Section", or...? Assuming the former, you could say something like "We also strongly encourage you to define explicit labels for all major sections. For example, to label a section with the name "section-label":

          Lists:

          I suggest moving this before sections and showing the rendered results.

          You say earlier "Note that numbered lists require four or more spaces,", but I don't see that in the example and I'm very relieved, as it seems like a bad rule to require different indenting for numbered lists than for unordered lists. In any case, if that note DOES have some validity then I suggest you move it to this section and explain it in more depth.

          ReStructuredText Style Guide

          • you say "Content in directives should be indented by three spaces" but our coding standards call for 4 spaces per tab. Can we please use 4 spaces, instead? Much reST documentation will be mixed with code, so it would make our lives much easier in those situations, and even for pure reST files it saves having to rejigger editor settings.

          Wrapping

          • You recommend soft wrapping, but please tell us which kinds of files should use soft wrapping. Source files have a line length limit of 110 characters, so we can't use soft wrapping for those. I am guessing you mean pure reST files, e.g. package overviews (our current main.dox files).

          This may just be me, but I find the style of mixing sentence structure with bullet lists a bit confusing. For example:

          ...softwrapping, which has the concrete advantages of
          • lettings others format text columns in their editors as they wish, and
          • making it easier to accept doc changes via GitHub Flow in the Browser, where auto-hardwrapping isn’t done.
          

          I would probably write that as multiple sentences (to avoid run-on) and skip the bullets, e.g.:

          ...soft wrapping. This allows others to format text columns in their editors as they wish. It also simplifies doc changes via GitHub Flow in the Browser, where automatic hard wrapping isn’t done.
          

          But if you prefer bullets, I suggest removing the sentence cues, e.g.:

          soft wrapping. This has the concrete advantages of:
          • Allowing others format text columns in their editors as they wish.
          • Making it easier to accept doc changes via GitHub Flow in the Browser, where automatic hard wrapping isn’t done.
          

          I have no idea what "doc changes via GitHub Flow in the Browser" means. Please explain. Also, what is "the Browser" and why is it capitalized? If you mean a web browser then I suggest "your web browser" instead of "the Browser", since the word "browser" is generic.

          This is as far as I've gotten, but I'll ask you to take another editing pass before I look at it again. While you are doing this, please look for typos and such. Here is what I've found so far:

          • An extra "the" in "summarizing the all the reST"
          • lettings -> letting in "lettings others format text"
          • Please delete the last comma in "Emacs users, for example, are free, to hardwrap"
          • I don't think "softwrap" and "hardwrap" are commonly accepted words; I suggest a space before the "wrap".
          • "When softwrapping": I suggest "When using soft wrapping", to avoid treating wrapping as a verb
          • Please don't use "markup" as a verb (e.g. "To markup emphasized text"). I suggest simpler phrasing, such as the following (which also shows that spaces are acceptable):

              Italics: *text in italics* -> text in italics
              Bold text: **bold text** -> bold text
              Monospaced text: ``monospace text`` -> monospace text
              For inline equations use role math...
            

          rowen Russell Owen added a comment - As a reST newbie I would ask you to consider some rearrangement of content. I found the beginning quite hard to understand due to lack of examples and context. In particular I found it unenlightening and intimidating to hear about Roles, Directives or wrapping rules before having any idea what they are used for or what reST looks like. I suggest you start with basic formatting first, e.g. inline text styling, lists, possibly links, and sections (roughly in that order). Then, after we have the basics you can talk about Roles and Directives with something concrete to refer back to. However, if you prefer the current arrangement then it might suffice to start with an example (showing the source and the formatted result). I am quite concerned about your suggestion to use 3 spaces for indenting. Our source code uses 4 spaces/tab stop and it would be much easier to use 4 spaces when writing reST in source code. Even for pure reST files it would be handy to stick with 4 spaces, since one need to fine-tune the editor based on file type, and since then one can use the same standard in source code and out, and copy/past reST between the two without worrying about changing the indentation. Thank you for the section "inline styles can't be nested" and the next section. I found that very helpful, as I often run into this, e.g. when using markdown. However, your inline example doesn't quite nest properly; the final two characters (*`) should be swapped. A typo? I suggest not using a footnote for monospace in source code, since developers will write a huge fraction of their reST in source code. I suggest listing both options in the same place, e.g.: monospace in source code uses single backticks: ... monospace in pure reST files uses double backticks: ... It is a pity that distinction exists, but I assume we are stuck with it. Sections: this would be clearer by just showing the examples (without the initial list) and, if possible, the results. For instance I have no idea what "Page title: # with overline" means until I see the example below, and the example is sufficient (though it is not clear to me if the leading and trailing # are needed or convention or...). Hence I would ditch the list, or integrate the examples with the list items. If you do keep the list, please don't number it, as the numbers don't seem to add information. I realize showing results will be hard, since cluttering the text with extra section dividers could be confusing. Inset graphics would be great, but might be too much work. A link to a page showing the results of the example would probably suffice. (I wish we could use in-line commands, such as "h1.", instead of underlines, but that's just me.) What does this note mean: "Note that reST will automatically map section characters to HTML header levels based on the order in which they appear. Using this hierarchy, however, is strongly recommended for consistency"? I don't understand your example of a section label. What is the name of the section? Is it "section-label" or is that a reST command and the name is "Title of the Section", or...? Assuming the former, you could say something like "We also strongly encourage you to define explicit labels for all major sections. For example, to label a section with the name "section-label": Lists: I suggest moving this before sections and showing the rendered results. You say earlier "Note that numbered lists require four or more spaces,", but I don't see that in the example and I'm very relieved, as it seems like a bad rule to require different indenting for numbered lists than for unordered lists. In any case, if that note DOES have some validity then I suggest you move it to this section and explain it in more depth. ReStructuredText Style Guide you say "Content in directives should be indented by three spaces" but our coding standards call for 4 spaces per tab. Can we please use 4 spaces, instead? Much reST documentation will be mixed with code, so it would make our lives much easier in those situations, and even for pure reST files it saves having to rejigger editor settings. Wrapping You recommend soft wrapping, but please tell us which kinds of files should use soft wrapping. Source files have a line length limit of 110 characters, so we can't use soft wrapping for those. I am guessing you mean pure reST files, e.g. package overviews (our current main.dox files). This may just be me, but I find the style of mixing sentence structure with bullet lists a bit confusing. For example: ...softwrapping, which has the concrete advantages of • lettings others format text columns in their editors as they wish, and • making it easier to accept doc changes via GitHub Flow in the Browser, where auto-hardwrapping isn’t done. I would probably write that as multiple sentences (to avoid run-on) and skip the bullets, e.g.: ...soft wrapping. This allows others to format text columns in their editors as they wish. It also simplifies doc changes via GitHub Flow in the Browser, where automatic hard wrapping isn’t done. But if you prefer bullets, I suggest removing the sentence cues, e.g.: soft wrapping. This has the concrete advantages of: • Allowing others format text columns in their editors as they wish. • Making it easier to accept doc changes via GitHub Flow in the Browser, where automatic hard wrapping isn’t done. I have no idea what "doc changes via GitHub Flow in the Browser" means. Please explain. Also, what is "the Browser" and why is it capitalized? If you mean a web browser then I suggest "your web browser" instead of "the Browser", since the word "browser" is generic. This is as far as I've gotten, but I'll ask you to take another editing pass before I look at it again. While you are doing this, please look for typos and such. Here is what I've found so far: An extra "the" in "summarizing the all the reST" lettings -> letting in "lettings others format text" Please delete the last comma in "Emacs users, for example, are free, to hardwrap" I don't think "softwrap" and "hardwrap" are commonly accepted words; I suggest a space before the "wrap". "When softwrapping": I suggest "When using soft wrapping", to avoid treating wrapping as a verb Please don't use "markup" as a verb (e.g. "To markup emphasized text"). I suggest simpler phrasing, such as the following (which also shows that spaces are acceptable): Italics: *text in italics* -> text in italics Bold text: **bold text** -> bold text Monospaced text: ``monospace text`` -> monospace text For inline equations use role math...

          I believe I have addressed all of concerns above with new commits. The reST Style guide should be updated at http://docs.lsst.codes/en/tickets-dm-4001/development/docs/rst_styleguide.html

          For indentation, we have experiment found that reST parsers are flexible about the exact amount of indentation. Instead of specifying indentation sizes, I've instead emphasized that the reST standard is to align content with it's context. This applies to lists, content in directives, etc. This is a Python/reST community convention.

          jsick Jonathan Sick added a comment - I believe I have addressed all of concerns above with new commits. The reST Style guide should be updated at http://docs.lsst.codes/en/tickets-dm-4001/development/docs/rst_styleguide.html For indentation, we have experiment found that reST parsers are flexible about the exact amount of indentation. Instead of specifying indentation sizes, I've instead emphasized that the reST standard is to align content with it's context. This applies to lists, content in directives, etc. This is a Python/reST community convention.
          rowen Russell Owen added a comment - - edited

          This is much improved! I still have a lot to say, but it's pickier stuff and I read the whole thing this time.

          Please consider including the extra information about section headings in the example itself, for instance:

          ###########################
          Titles and Section Headings
          ###########################
           
          Titles have hash marks above and below.
           
          By convention titles and section headings are set off from surrounding text by at least one blank line.
          However, in Python docstrings we prefer that you not use a blank line below a section heading,
          and only the last three section types (subsection and lower) are supported.
           
          All levels of section headings may have named labels, which appear before the heading. We encourage you to add labels to all sections so that they can be referenced. Names are global, so be specific. See _ref:`Internal Links to Labels <internal-links-to-labels>\" for more information. The following section heading has a label named "section-headings-example-section-heading":
           
          .. _example-section-heading:
           
          Section Heading
          ===============
           
          Section headings are underlined with equals signs. Again note the blank lines before and after.
           
          .. _example-subsection-heading:
           
          Subsection Heading
          ------------------
           
          Subsection headings are underlined with dashes.
           
          .. _example-sub-subsection-heading:
           
          Sub-subsection heading
          ^^^^^^^^^^^^^^^^^^^^^^
           
          Sub-subsection headings are underlined with carets.
           
          Sub-sub-subsection Heading
          """"""""""""""""""""""""""
           
          Sub-sub-subsection headings are underlined with double quotes.
          (You'll note that I changed "paragaraph" heading to "sub-sub-subsection" for consistency and because paragraphs don't usually have headings.)
          

          Would it be fairly easy to provide a link to a page that renders this example?

          Typo: "When referring to code objects, it’s better to use different that links to...": Perhaps a missing word between "different" and "that links"? If so, I suspect you'll want "link", not "links".

          What does this mean: "This specific sequence of section markup styles is not mandated by the reST specification, but we encourage you to use it for consistency across all reST documents."? I am guessing it means the association between section level and underlining character is arbitrary, but if so, the rest of the text implies you could use anything you wanted, which seems odd to me. Surely we provide the config file that specifies it? If so, you might say something about that (e.g. this is the LSST convention, as specified in our standard configuration file).

          External links: why the underscore in "`PEP8 style guide`_."? Is it needed?

          Is it a documented standard to prefer the first style, or your suggestion based on readability? I hate the repetition and fragility, though I agree about readability. It is a pity that the non-repetitive style cannot include a carriage return between the link text and the link.

          Lnks to Code Objects:

          I found the sentence "See Sphinx's documentation..." disconcerting, as if the sentence before was all you were going to say on the subject. I was pleasantly surprised when you provided examples. I suggest you move that sentence after the examples. Another option is to change it to something like this:
          "Here are some examples. For more information see Sphinx's documentation...". Also, it is not clear to me how this link relates to the other links below (which go to different locations but also provide more information).

          This sentence could use some work: "For example, in docstrings for a class references to methods in the same class can be specified by method name alone."

          I suggest changing "concisely" to "concise" in "code references can be made more concisely"

          What does this mean: "Note that images are included in the _static/ directory of the docs;"? Is it a convention that there is a directory named "_static"? It is particularly confusing because it's not clear which text is exact and which needs to be replaced with a real path. Showing the the replaceable bits in italics or surrounding them with "<>" or might help.

          I'm still not sure what to do about the terms such as "role". Your initial explanation before getting into formatting seemed out of place, but now what to do? You use the term a lot without defining it. I do see the point in using correct terminology, but only if it truly helps the user understand what is going on. Often it seems superfluous, in which case deleting the word may actually make the text easier to understand. If it is useful in some cases then perhaps you could provide a definition or make the word a link to a brief explanation?

          Python docs

          Boilerplate: we have an RFC that was accepted (I thought) to cut this way down. I don't want to hold up your docs, but if you have not already done so, I encourage you to ask if we have an acceptable short form. (This also applies to C++ documentation, of course).

          "Single line docstrings should have the delimiters and text all on one line". Is this a published standard? I strongly disagree with it, because I think it encourages poor documentation by encouraging developers to write overly brief documentation in the first place, and discourages others from expanding existing documentation by making it more of a hassle. I would prefer to act as if all methods, etc. deserve multiple lines of documentation, even though a small minority may not require it. That said, I do understand that accessors and the like usually don't need much documentation. On the other hand we are moving away from use of accessors in Python.

          You might mention that by convention the summary line is a written as a present tense action, e.g. "Save the content" rather than "Saves the content".

          More module-level doc strings, surely we put the sh-bang line first, if there is one? How about "from _future_ import..."?
          I've generally stuck both up top, because they have to appear first to be effective. This reduces the danger of somebody breaking them by putting something above them (especially a concern with from _future_, though I am sure there would be a useful error message).

          I suggest "Class/method/function docstrings should be placed" -> "... must be placed" because this is not optional in Python

          I am concerned that you change section terminology here. It would be easier if section heading names had the same names and underline characters in .rst files and .py files. I suggest changing your terminology in the python section.

          "required by out Sphinx tooling" out -> our

          "Our Coding Style Guide allows for Python lines to be as long as 110 lines. However docstring lines must be 75 characters or fewer to facilitate reading in the terminal or Jupyter notebook contexts" Please don't make such rules without an RFC or other chance for us to weigh in. I strongly oppose any reduction in line length. Terminals and Jupyter notebooks can be made as wide as needed.

          Is the word "keyword" useful in "If it is not necessary to specify a keyword argument..."?

          When documenting function parameters, based on your example, ", optional" is omitted for an optional parameter if a default value is described. Is that correct?

          Extra trailing underscore in "func_b, func_c_, func_d"

          Documenting C++

          Your format does not match any exising C++ that I found, even though we have a variety and could probably use some whittling down. In particular the brief line always goes on the line after the introductory /**. The following is typical, though does not include parameters:

          /**
           * @brief Alternate interface to afw::math::warpImage()
           * in which the caller does not need to precompute the output bounding box.
           *
           * We preserve the convention of warpImage() that the affine transform is inverted,
           * so that the output and input images are related by:
           *   out[p] = in[A^{-1}p]
           *
           * The input image is assumed zero-padded.
           */
          

          Other facts that might be useful:

          One-liners often begin with ///. This is a style I dislike for the same reason I dislike """brief python doc""": it encourages writing overly brief documentation and discourages future users from filling out existing documentation. That said, C++ is filled with getters and setters, for which one-liners are usually sufficient, if wanted at all.

          We did agree that docs belong in .h rather than .cc, but not all code has changed yet because we rarely go back and update older code to newer conventions. I wish we could find time to make these changes.

          Parameters can be documented where they appear using @param in the comment block, or ///< after the param in the argument list itself. I think most folks prefer the former, and I suggest it as our standard. We started with ///< so as to not keep the doc closer to the code, but Doxygen whines if you get your @param out of synch with the param names, so it's not that big a deal (except these days Doxygen prints too many warnings, due to our attempts to link out-of-package, so we tend to ignore the warnings).

          We have a mix of backslash and @ to indicate Doxygen comments. We started with backslash and then switched to @ because some tool could not handle backslash, but I don't know if that tool is still used and if anyone cares anymore. I personally find @ nicer to look at, but that's just me.

          rowen Russell Owen added a comment - - edited This is much improved! I still have a lot to say, but it's pickier stuff and I read the whole thing this time. Please consider including the extra information about section headings in the example itself, for instance: ########################### Titles and Section Headings ###########################   Titles have hash marks above and below.   By convention titles and section headings are set off from surrounding text by at least one blank line. However, in Python docstrings we prefer that you not use a blank line below a section heading, and only the last three section types (subsection and lower) are supported.   All levels of section headings may have named labels, which appear before the heading. We encourage you to add labels to all sections so that they can be referenced. Names are global, so be specific. See _ref:`Internal Links to Labels <internal-links-to-labels>\" for more information. The following section heading has a label named "section-headings-example-section-heading":   .. _example-section-heading:   Section Heading ===============   Section headings are underlined with equals signs. Again note the blank lines before and after.   .. _example-subsection-heading:   Subsection Heading ------------------   Subsection headings are underlined with dashes.   .. _example-sub-subsection-heading:   Sub-subsection heading ^^^^^^^^^^^^^^^^^^^^^^   Sub-subsection headings are underlined with carets.   Sub-sub-subsection Heading """"""""""""""""""""""""""   Sub-sub-subsection headings are underlined with double quotes. (You'll note that I changed "paragaraph" heading to "sub-sub-subsection" for consistency and because paragraphs don't usually have headings.) Would it be fairly easy to provide a link to a page that renders this example? Typo: "When referring to code objects, it’s better to use different that links to...": Perhaps a missing word between "different" and "that links"? If so, I suspect you'll want "link", not "links". What does this mean: "This specific sequence of section markup styles is not mandated by the reST specification, but we encourage you to use it for consistency across all reST documents."? I am guessing it means the association between section level and underlining character is arbitrary, but if so, the rest of the text implies you could use anything you wanted, which seems odd to me. Surely we provide the config file that specifies it? If so, you might say something about that (e.g. this is the LSST convention, as specified in our standard configuration file). External links: why the underscore in "`PEP8 style guide`_."? Is it needed? Is it a documented standard to prefer the first style, or your suggestion based on readability? I hate the repetition and fragility, though I agree about readability. It is a pity that the non-repetitive style cannot include a carriage return between the link text and the link. Lnks to Code Objects: I found the sentence "See Sphinx's documentation..." disconcerting, as if the sentence before was all you were going to say on the subject. I was pleasantly surprised when you provided examples. I suggest you move that sentence after the examples. Another option is to change it to something like this: "Here are some examples. For more information see Sphinx's documentation...". Also, it is not clear to me how this link relates to the other links below (which go to different locations but also provide more information). This sentence could use some work: "For example, in docstrings for a class references to methods in the same class can be specified by method name alone." I suggest changing "concisely" to "concise" in "code references can be made more concisely" What does this mean: "Note that images are included in the _static/ directory of the docs;"? Is it a convention that there is a directory named "_static"? It is particularly confusing because it's not clear which text is exact and which needs to be replaced with a real path. Showing the the replaceable bits in italics or surrounding them with "<>" or might help. I'm still not sure what to do about the terms such as "role". Your initial explanation before getting into formatting seemed out of place, but now what to do? You use the term a lot without defining it. I do see the point in using correct terminology, but only if it truly helps the user understand what is going on. Often it seems superfluous, in which case deleting the word may actually make the text easier to understand. If it is useful in some cases then perhaps you could provide a definition or make the word a link to a brief explanation? Python docs Boilerplate: we have an RFC that was accepted (I thought) to cut this way down. I don't want to hold up your docs, but if you have not already done so, I encourage you to ask if we have an acceptable short form. (This also applies to C++ documentation, of course). "Single line docstrings should have the delimiters and text all on one line". Is this a published standard? I strongly disagree with it, because I think it encourages poor documentation by encouraging developers to write overly brief documentation in the first place, and discourages others from expanding existing documentation by making it more of a hassle. I would prefer to act as if all methods, etc. deserve multiple lines of documentation, even though a small minority may not require it. That said, I do understand that accessors and the like usually don't need much documentation. On the other hand we are moving away from use of accessors in Python. You might mention that by convention the summary line is a written as a present tense action, e.g. "Save the content" rather than "Saves the content". More module-level doc strings, surely we put the sh-bang line first, if there is one? How about "from _ future _ import..."? I've generally stuck both up top, because they have to appear first to be effective. This reduces the danger of somebody breaking them by putting something above them (especially a concern with from _ future _, though I am sure there would be a useful error message). I suggest "Class/method/function docstrings should be placed" -> "... must be placed" because this is not optional in Python I am concerned that you change section terminology here. It would be easier if section heading names had the same names and underline characters in .rst files and .py files. I suggest changing your terminology in the python section. "required by out Sphinx tooling" out -> our "Our Coding Style Guide allows for Python lines to be as long as 110 lines. However docstring lines must be 75 characters or fewer to facilitate reading in the terminal or Jupyter notebook contexts" Please don't make such rules without an RFC or other chance for us to weigh in. I strongly oppose any reduction in line length. Terminals and Jupyter notebooks can be made as wide as needed. Is the word "keyword" useful in "If it is not necessary to specify a keyword argument..."? When documenting function parameters, based on your example, ", optional" is omitted for an optional parameter if a default value is described. Is that correct? Extra trailing underscore in "func_b, func_c_, func_d" Documenting C++ Your format does not match any exising C++ that I found, even though we have a variety and could probably use some whittling down. In particular the brief line always goes on the line after the introductory /**. The following is typical, though does not include parameters: /** * @brief Alternate interface to afw::math::warpImage() * in which the caller does not need to precompute the output bounding box. * * We preserve the convention of warpImage() that the affine transform is inverted, * so that the output and input images are related by: * out[p] = in[A^{-1}p] * * The input image is assumed zero-padded. */ Other facts that might be useful: One-liners often begin with /// . This is a style I dislike for the same reason I dislike """brief python doc""": it encourages writing overly brief documentation and discourages future users from filling out existing documentation. That said, C++ is filled with getters and setters, for which one-liners are usually sufficient, if wanted at all. We did agree that docs belong in .h rather than .cc, but not all code has changed yet because we rarely go back and update older code to newer conventions. I wish we could find time to make these changes. Parameters can be documented where they appear using @param in the comment block, or ///< after the param in the argument list itself. I think most folks prefer the former, and I suggest it as our standard. We started with ///< so as to not keep the doc closer to the code, but Doxygen whines if you get your @param out of synch with the param names, so it's not that big a deal (except these days Doxygen prints too many warnings, due to our attempts to link out-of-package, so we tend to ignore the warnings). We have a mix of backslash and @ to indicate Doxygen comments. We started with backslash and then switched to @ because some tool could not handle backslash, but I don't know if that tool is still used and if anyone cares anymore. I personally find @ nicer to look at, but that's just me.
          rowen Russell Owen added a comment - - edited

          I'm done with my review. jmatt can you please mark this as Reviewed when you are done reviewing it?

          rowen Russell Owen added a comment - - edited I'm done with my review. jmatt can you please mark this as Reviewed when you are done reviewing it?

          Thanks Russell for your review. I appreciate that it's a lot of get through, but all writers benefit from editors.

          As for your comments about the C++ documentation, I'll confess that this is a part I haven't figured out and simply deferred to porting over the Confluence page https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards and re-organizing that where I could. Maybe I should leave the C++ documentation advice out of this ticket until I a) figure out how C++ and Python docs interact via SWIG and b) figure out how Doxygen interacts with Sphinx before giving advice.

          jsick Jonathan Sick added a comment - Thanks Russell for your review. I appreciate that it's a lot of get through, but all writers benefit from editors. As for your comments about the C++ documentation, I'll confess that this is a part I haven't figured out and simply deferred to porting over the Confluence page https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards and re-organizing that where I could. Maybe I should leave the C++ documentation advice out of this ticket until I a) figure out how C++ and Python docs interact via SWIG and b) figure out how Doxygen interacts with Sphinx before giving advice.

          +1

          Comments are in the GitHub PR.

          jmatt J Matt Peterson [X] (Inactive) added a comment - +1 Comments are in the GitHub PR.

          Things to be carried forward in future stories:

          1. Best policy for referring to DM tickets and RFCs unobtrusively
          2. Good way to include asides and signposts special case audiences
          jsick Jonathan Sick added a comment - Things to be carried forward in future stories: Best policy for referring to DM tickets and RFCs unobtrusively Good way to include asides and signposts special case audiences

          People

            jsick Jonathan Sick
            jsick Jonathan Sick
            J Matt Peterson [X] (Inactive)
            Frossie Economou, J Matt Peterson [X] (Inactive), Jonathan Sick, Russell Owen
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Jenkins

                No builds found.