Homework 2
Spring 2023
Due: F 2/17 @ 5 PM
3 points
This homework is to give you some practice writing documentation (doc) comments and using doxygen to generate documentation from those doc comments. By default, doxygen produces documentation in two formats: HTML and LaTeX (pronounced 'lay-TEK'). HTML is the hyper-text markup language, which one uses for writing Web pages. LaTeX is a typesetting program widely used to produce technical publications. After producing documentation in these formats, as an optional exercise, you can generate a PDF file using the documentation in LaTeX and publish a Web page using the documentation in HTML.
Note that in order to complete this homework you need to fix any problems with your doc comments. When you run doxygen on your source code, it prints error messages for the problems it finds.
I have created a few screencast on using doc comments to document classes and methods:
The classes store and manipulate information about individual playing cards, a deck of cards, and a hand of cards. There are also routines for calculating the value of a hand for Blackjack.
cs-class-1% cp ~maloofm/cosc052/hw2.zip ./ cs-class-1% unzip hw2.zip Archive: hw2.zip inflating: hw2/deck.cpp inflating: hw2/hand.h inflating: hw2/card.h inflating: hw2/main.cpp inflating: hw2/deck.h inflating: hw2/Makefile.dep inflating: hw2/main.h inflating: hw2/hand.cpp inflating: hw2/Makefile inflating: hw2/card.cpp cs-class-1% rm hw2.zip cs-class-1% cd hw2In the hw2 directory you'll see classes for storing and manipulating information about a deck of playing cards and for drawing hands from a deck of cards. You can compile the project using the Makefile. The main function draws a hand of five random cards from the deck, prints the hand to the console, and prints its value.
In the .h files, write class and data member documentation comments. In the .cpp files, write method documentation comments. You do not need to document the main function. Use tags @author, @version, @param, @return, and @throws, where appropriate.
To run doxygen on the source in the directory, type
cs-class-1% cd hw2 cs-class-1% doxygen -g cs-class-1% doxygenThe first command generates a configuration file named Doxyfile. The second command grabs and processes the doc comments present in all of your .h and .cpp files. You can also type 'make docs'.
You should see an obscene amount of output, but eventually you should return to the cs-class-1 prompt. After listing the contents of the directory, you should see two new directories: html and latex. When you get to this point, you can type 'make clean' and then 'make submit' to produce the file submit.zip that you can upload to Autolab.
In its default setting, doxygen does not generate documentation for private data members and methods, since programmers using classes under normal circumstances can't access those elements. Of course programmers who are implementing classes using generated documentation will need to see the comments for private data members and methods. And for this homework you do need to document private elements.
It is not requied, but if you want to generate documentation for private data members and methods, you can open the file Doxyfile and search for EXTRACT. You should see
... EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. EXTRACT_PRIVATE = NO ...If you change NO to YES on both of those lines and rerun doxygen (not doxygen -g), then doxygen will generate documentation for the private data members and methods.
Before submitting be sure to include the honor statement. In a file named HONOR, include the following statement with the appropriate modifications:
In accordance with the class policies and Georgetown's Honor System, I certify that, with the exceptions of the class resources and those items noted below, I have neither given nor received any assistance on this project. Name NetID
As optional exercises, you can generate PDF documentation, HTML documentation, or both. For each of these, a transcript of my session appears below.
cs-class-1% cd latex cs-class-1% lsYou'll see a bunch of files, but you should see your friend, the Makefile.
Be bold and type 'make'. You will again see an obscene amount of output, but when it stops, again list the contents of the directory. You should see a number of files with the root 'refman', which is an abbreviation for reference manual. There should be a file named refman.pdf. You can transfer that file to your laptop and view it like any other PDF file.
The following is a transcript of my session. Bold type denotes commands I typed.
cs-class-1% cd hw2
cs-class-1% ls
card.cpp deck.cpp hand.cpp main.cpp Makefile
card.h deck.h hand.h main.h Makefile.dep
cs-class-1% doxygen -g
cs-class-1% doxygen
Searching for include files...
Searching for example files...
...
Generating example index...
Generating file member index...
cs-class-1% ls
card.cpp deck.cpp hand.cpp html/ main.cpp Makefile
card.h deck.h hand.h latex/ main.h Makefile.dep
cs-class-1% cd latex
cs-class-1% ls
annotated.tex classDeck.tex doxygen.sty refman.tex
classCard.tex classHand.tex Makefile
cs-class-1% make
rm -f *.ps *.dvi *.aux *.toc *.idx *.ind *.ilg *.log *.out refman.pdf
pdflatex refman.tex
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
...
Output written on refman.pdf (14 pages, 118435 bytes).
Transcript written on refman.log.
latex_count=5 ; \
while egrep -s 'Rerun (LaTeX|to get cross-references right)' refman.log && [ $latex_count -gt 0 ] ;\
do \
echo "Rerunning latex...." ;\
pdflatex refman.tex ;\
latex_count=`expr $latex_count - 1` ;\
done
cs-class-1% ls
annotated.tex classDeck.tex doxygen.sty refman.idx refman.log refman.tex
classCard.tex classHand.aux Makefile refman.ilg refman.out refman.toc
classDeck.aux classHand.tex refman.aux refman.ind refman.pdf
cs-class-1% ls refman.pdf
refman.pdf
cs-class-1%
Log on to cs-class-1.
The first step is to open two directories to the Web server. Unix has three types of privileges: u for user privilege, g for group privilege, and o for other privilege. For files and directories, each type has three permissions: r is for read permission, w is for write permission, and x is for execute permission.
If you do a long listing of the files in your directory by typing 'ls -l' at the prompt, the string in the first column of the listing shows the privileges of the files and directories (e.g, -rw-rw----). There are 10 positions. The first position indicates whether the file is a directory. Normal files have a hyphen in the first position; directories have a 'd'. The next nine positions show the read, write, and execute access for users, groups, and others, respectively. There are three types and three permissions for each type.
To set file and directory privileges, we use the chmod command, which changes the mode of files and directories.
To specify the mode for directories and files, we use a string that consists of references, an operator, and modes. References designate the type: u for user, g for group, o for other, and a for all. An operator is either +, which adds permissions, or -, which removes permissions. Finally, the modes are the permissions: r is for read, w is for write, and x is for execute. X sets execute privilege for directories, but not files. (We call also use three octal digits where each digit corresponds to user, group, and other, and each digit's bits correspond to read, write, and execute.)
As an example, if we wanted to give everyone execute privilege to the directory test, we would write 'chmod a+x test'. If we wanted to turn off all group and other privileges for all files in a directory, then we would write 'chmod go-rwx *'.
To set the privileges for your home directory, type:
cs-class-1% cd <-- Takes you to your home directory cs-class-1% cd .. <-- Moves up to the parent directory cs-class-1% chmod o+rx <your-netid> <-- Adds read and execute permission for other cs-class-1% ls -l | grep <your-netid> <-- Lists the files and searches (greps) for your netid drwxr-xr-x 20 <your-netid> <your-netid> 4096 Feb 9 14:57 <your-netid>/If you don't see the the permissions string drwxr-xr-x, then something didn't work, and you should come see me before proceeding.
The next step is to create the directory for your Web pages. By default, the Web server on cs-class-1 always serves pages from the user directory public_html. Once created, you'll need to set the correct permissions, which must be read and execute for others. To do this, type the following:
cs-class-1% cd <-- Takes you to your home directory cs-class-1% mkdir public_html <-- Makes the directory public_html cs-class-1% chmod o+rx public_html <-- Adds read and execute permission for otherTo test that you've configured your Web directory correctly, descend into the public_html directory, copy the simple Web page from my cosc052 directory, and set the file's permissions so others have read permission:
cs-class-1% cd public_html <-- Descends into public_html cs-class-1% cp ~maloofm/cosc052/index.html ./ <-- Copies the Web page into the current directory cs-class-1% chmod o+r index.html <-- Adds read permission for other cs-class-1% ls -l index.html <-- Displays the long listing of the file -rw-r--r-- 1 <your-netid> <your-netid> 37 Jan 18 22:12 index.htmlNext, go to your favorite Web browser, and see if cs-class-1 will serve you the page. Type the following URL with the appropriate substitution into the address bar:
http://cs-class-1.uis.georgetown.edu/~<your-netid>The string "Hello!" should appear in your browser, along with a dead link to "HW2 Documentation." If this doesn't work, guess what? Come see me.
The next step is to make a directory for your documentation, copy it from your hw2 directory, and set the proper file and directory permissions. Use pwd to make sure you're in the public_html directory. If you are not, then type:
cs-class-1% cd cs-class-1% cd public_htmlOnce in the public_html directory, type
cs-class-1% mkdir hw2docs <-- Makes a directory named hw2docs cs-class-1% cd hw2docs <-- Descends into the directory hw2docs cs-class-1% cp -r ~/hw2/html/* ./ <-- Copies recursively the contents of hw2/html to the current directory cs-class-1% cd .. <-- Moves up to the directory public_html cs-class-1% chmod -R o+rX hw2docs <-- Adds read and execute permissions recursively for other for the directory hw2docsAssuming that your documentation is in the directory $HOME/hw2/html, you should be able to use your browser to click the link to "HW2 Documentation". Click around and check it out.
N.B. At this point, the directory public_html is a public directory, so do not put anything in that directory that you don't want everyone on the Internet to access. After completing this step, if you want to take down your Web pages, you can change the permissions of the files and directories:
cs-class-1% cd <-- Takes you to your home directory cs-class-1% chmod -R o-rx public_html <-- Recursively removes read and execute privilege for other for public_html and all files and directories thereinIf you want to completely remove these directories and files, type the rather dangerous command:
cs-class-1% cd <-- Takes you to your home directory cs-class-1% rm -r public_html <-- Recursively removes public_html and all therein
A transcript of my session follows:
cs-class-1% cd cs-class-1% cd .. cs-class-1% chmod o+rx maloofm cs-class-1% ls -l | grep maloofm drwxr-xr-x 19 maloofm maloofm 4096 Feb 9 16:09 maloofm/ cs-class-1% cd cs-class-1% mkdir public_html cs-class-1% chmod o+rx public_html cs-class-1% cd public_html cs-class-1% cp ~maloofm/cosc052/index.html ./ cs-class-1% ls -l index.html -rw-rw---- 1 maloofm maloofm 103 Feb 9 16:11 index.html cs-class-1% chmod o+r index.html cs-class-1% ls -l index.html -rw-rw-r-- 1 maloofm maloofm 103 Feb 9 16:11 index.html cs-class-1% pwd /home/maloofm/public_html cs-class-1% mkdir hw2docs cs-class-1% ls index.html hw2docs/ cs-class-1% cd hw2docs cs-class-1% cp -r ~/hw2/html/* ./ cs-class-1% ls annotated.html classHand.html functions.html tab_b.gif card_8h_source.html classHand-members.html functions_vars.html tab_l.gif classCard.html deck_8h_source.html hand_8h_source.html tab_r.gif classCard-members.html doxygen.css index.html tabs.css classDeck.html doxygen.png installdox* classDeck-members.html files.html main_8h_source.html classes.html functions_func.html search/ cs-class-1% cd .. cs-class-1% chmod -R o+rX hw2docs cs-class-1%
Copyright © 2023 Mark Maloof. All Rights Reserved. This material may not be published, broadcast, rewritten, or redistributed.