# Ticket #8804(closed enhancement: fixed)

Opened 3 years ago

## Bring plot/plot3d/parametric_surface.pyx to 100% doctest coverage

Reported by: Owned by: kcrisman mvngu minor sage-4.4.2 documentation robertwb N/A Minh Van Nguyen Karl-Dieter Crisman sage-4.4.2.rc0

### Description

Bring plot/plot3d/parametric_surface.pyx to 100% doctest coverage.

## Change History

### Changed 3 years ago by kcrisman

Based on Sage 4.4

### comment:1 Changed 3 years ago by kcrisman

• Status changed from new to needs_review
• Authors set to Karl-Dieter Crisman

Also fixes a few inconsistencies with formula for MobiusStrip? that wasn't used and dual() that I checked with robertwb.

### comment:2 Changed 3 years ago by mvngu

• Reviewers set to Minh Van Nguyen

The patch  trac_8804-param-surface-docs.patch is OK by me. I have added a reviewer patch that fixes some typos, add the parametric surface module to the reference manual, and fixes to get the module to build and resolve all warnings. So only my patch needs review by anyone but me.

### comment:3 follow-up: ↓ 4 Changed 3 years ago by kcrisman

This looks okay, but I'm not sure how to test the documentation building and looking right. Also, just for my information, when do we need r""" and when is """ sufficient? Also, apparently the input for init goes in the class definition - is that right? My apologies, I didn't realize that.

### comment:4 in reply to: ↑ 3 Changed 3 years ago by mvngu

This looks okay, but I'm not sure how to test the documentation building and looking right.

A quick-and-dirty way is to rebuild as follows from SAGE_ROOT:

./sage -b main
./sage -docbuild reference html


If you really want to be thorough, you could delete the whole output directory resulting from building the Sage documentation and then rebuild the whole reference manual again. This would take much longer than the above quick-and-dirty way, but it sure is more thorough. From SAGE_ROOT, do:

rm -rf devel/sage-main/doc/output/
./sage -b main
./sage -docbuild reference html


Also, just for my information, when do we need r""" and when is """ sufficient?

We need r""" when the docstring contains LaTeX escapes, i.e. LaTeX macros that start with a backslash character. In most other cases, """ is sufficient. For example, if your docstring contains something like

\sin(x)^2 + \cos(x)^2 = 1


then your docstring must be delimited with r""". For safety, I always use r""".

Also, apparently the input for init goes in the class definition - is that right?

At the moment, that is the case because docstrings for methods and functions whose names start with an underscore don't show up on the reference manual. So full documentation for the constructor __init__ are recommended to be in the class docstring. That way, documentation relating to the constructor, including its input and output documentation, shows up on the reference manual.

### comment:5 Changed 3 years ago by kcrisman

• Status changed from needs_review to positive_review

Okay, looks great and still passes tests.

### comment:6 Changed 3 years ago by mvngu

• Status changed from positive_review to closed
• Resolution set to fixed
• Merged in set to sage-4.4.2.rc0
• Milestone changed from sage-5.0 to sage-4.4.2
Note: See TracTickets for help on using tickets.